npcpy

环境要求

• Python 环境与 pip（README 未指定最低版本）
• 可联网的终端用于下载依赖
• 可选：本地推理需安装 Ollama 及模型 qwen3.5:2b
• 可选：语音/TTS 功能需 portaudio、ffmpeg 等系统依赖
• 可选：使用云端模型需 OpenAI / Anthropic / Gemini 的 API Key

安装与启动步骤

1. 1安装 npcpy 基础包

   用 pip 从 PyPI 安装 npcpy 基础版本，只包含核心功能，不含各模型厂商的额外库。

   pip install npcpy

   复制

2. 2按需安装功能扩展

   本地模型、语音、云厂商 API 等能力分别放在不同 extra 中，按需要选择安装，npcpy[all] 为全量。

   pip install npcpy[local]
   pip install npcpy[yap]
   pip install npcpy[all]

   复制

3. 3安装 Linux 系统依赖

   Linux 下先装语音与图形相关系统包，再通过官方脚本安装 ollama 并拉取模型。

   sudo apt-get install espeak portaudio19-dev python3-pyaudio ffmpeg libcairo2-dev libgirepository1.0-dev
   curl -fsSL https://ollama.com/install.sh | sh
   ollama pull qwen3.5:2b

   复制

4. 4安装 macOS 系统依赖

   macOS 用 Homebrew 安装同类依赖和 ollama，并启动 ollama 后台服务后拉取模型。

   brew install portaudio ffmpeg pygobject3 ollama
   brew services start ollama
   ollama pull qwen3.5:2b

   复制

5. 5Windows 准备本地环境

   Windows 无命令行安装说明，需手动下载安装 Ollama 与 ffmpeg，再在终端拉取模型。

   ollama pull qwen3.5:2b

   复制

6. 6配置 API 密钥

   使用云端模型时把各家密钥写入 .env 文件，README 给出三个可配置的密钥变量。

   export OPENAI_API_KEY="your_key"
   export ANTHROPIC_API_KEY="your_key"
   export GEMINI_API_KEY="your_key"

   复制

关键配置

如何确认成功

运行 README 的 NPC 示例，若 print 成功输出 response 内容（如模型回复文本），说明库与模型接入正常。

常见问题

注意事项

• README 未指定 Python 最低版本，建议使用较新的 Python 3 环境。
• 本地模型示例默认使用 qwen3.5:2b（系统依赖步骤）与 qwen3.5:9b（代码示例），请先 ollama pull 对应模型。
• 知识图谱、智能体团队等高级用法需参考官方文档 npcpy.readthedocs.io。
• 示例中的 Jinx 路径如 npc_team/jinxes/analyze.jinx 需按自己项目的实际路径调整。