在项目中评估LLM-integration-play，可以先看清用途边界：在为 open-ch@t-studio 做出贡献时构建，以比较 LLM APIs 和重复错误，使用 AI 辅助开发进行实验。一旦进入软件开发环节，依赖、接口和异常处理往往比主路径更影响采用会直接影响交付，这也是我最关心的风险。更实际的做法是在隔离分支完成一个可回滚的小任务，同时核对安装步骤、接口契约、测试结果和错误信息，不要直接在关键项目上。对需要可检查开发流程而非单次演示的工程师来说，这个仓库值得继续验证；只求即装即用的人则要先看维护成本。

LLM 集成手册 (Jupyter)

该存储库包含用于测试和比较跨多个提供商和模型的 LLM 集成的 Jupyter 笔记本。

目标与学习

开始学习：

• SDK 跨 OpenAI、Gemini、Perplexity 和 Anthropic 的设置和身份验证
• API 风格差异（响应 API 与聊天完成）和特定于提供商的 endpoint/model 兼容性
• LangChain 与提供商无关的工作流程的抽象
• AI-辅助开发工作流程，包括AGENTS.md和SKILLS.md（带有GitHub Copilot，Claude代码）

结果是：

1. 诊断出 Dimagi Open Chat Studio 中的 错误 (OCS)：Perplexity 的声纳模型使用聊天完成样式，但其代理 API 使用 OpenAI-compatible /v1 基础URL。 OCS 的 LLM 抽象层没有考虑到这种分裂。调查还明确了OCS的LLM服务抽象层是如何构建的。
2. OpenAI 的响应 API file_search 工具在一次调用中成功搜索了 2 个向量存储，但硬上限为 2 — 第三个向量存储_id 抛出 400“最多允许 2 个向量存储”错误，确认了 Dimagi OCS 远程索引限制。

笔记本电脑

requirements.txt 保存所有笔记本共享的 Python 依赖项。

先决条件

• Python 3.12+（在 Linux 上测试）。
• VS 带有 Jupyter 扩展的代码。
• 您想要测试的 LLM 提供商的 API 密钥。

环境设置

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

在存储库根目录中创建 .env 文件：

OPENAI_API_KEY=
GOOGLE_API_KEY=
PERPLEXITY_API_KEY=
PPLX_API_KEY=
ANTHROPIC_API_KEY=

Perplexity.ipynb 使用 PERPLEXITY_API_KEY； LangChain-perplexity.ipynb 需要 PPLX_API_KEY — 您可以将两者设置为相同的值。

在 VS 代码中，打开笔记本并从 .venv 中选择 Python 内核。

AI 辅助开发和 CI

可选 - 预提交挂钩：

pip install pre-commit detect-secrets && pre-commit install 设置笔记本输出剥离、单元 lint/format 检查和提交时的秘密检测（.pre-commit-config.yaml 中的配置）。

依赖维护：

要求 Claude 使用 audit-dependencies 技能 (.agents/skills/audit-dependencies/SKILL.md) 检查 requirements.txt 中的 outdated/vulnerable 包并应用安全碰撞。 Claude 将创建一份有关审计的文档并提交 requirements.txt

可选 - 与 Claude 一起进行代码审查

该项目有一个 GitHub Actions 工作流程 (claude-code-review.yml)，它使用 Claude Code 进行审阅。在 PR 注释中提及 @claude 进行代码审查

可选 - 开发者实用程序 SKILLS

git-rebase：基于 dimagi 技能并更新以对此存储库有用

故障排除

• ValueError ... API_KEY environment variable not set:
  • 确保 .env 存在并且密钥已填充。
  • 确认笔记本内核使用与安装 python-dotenv 相同的 .venv。
• 401 Unauthorized :
  • 验证密钥有效性和帐户信用。
• 404 Not Found（困惑）：
  • 检查端点是否与 API 样式匹配（声纳聊天完成与代理 API）。
• Python 笔记本的按行运行和调试功能需要在笔记本内核中安装 ipykernel v6 或更高版本
  • pip install -U ipykernel

参考文献

请参阅 AGENTS.md 以获取 LLM API 文档的链接