Observability Langsmith 故障排查

# LangSmith 故障排除指南 ## 安装问题 ### 找不到包 **错误**: `ModuleNotFoundError: No module named 'langsmith'` **修复**: bash pip install langsmith # 验证安装 python -c "import langsmith; print(langsmith.__version__)" ### 版本冲突 **错误**: `ImportError: cannot import name 'traceable' from 'langsmith'` **修复**: bash # 升级到最新版本 pip install -U langsmith # 检查冲突 pip check # 如果存在冲突，创建干净的环境 python -m venv venv source venv/bin/activate pip install langsmith ## 身份验证问题 ### 找不到 API Key **错误**: `LangSmithAuthError: Authentication failed` **解决方案**: 1. **设置环境变量**: bash export LANGSMITH_API_KEY="your-api-key" # 或在 .env 文件中 LANGSMITH_API_KEY=your-api-key 2. **直接传递给客户端**: python from langsmith import Client client = Client(api_key="your-api-key") 3. **验证 Key 是否已设置**: python import os print(os.environ.get("LANGSMITH_API_KEY", "NOT SET")) ### 无效的 API Key **错误**: `LangSmithAuthError: 401 Unauthorized` **修复**: bash # 在 https://smith.langchain.com/settings 验证 Key # 测试连接 python -c "from langsmith import Client; c = Client(); print(list(c.list_projects()))" ### 错误的端点 **错误**: `LangSmithConnectionError: Connection refused` **修复**: python import os # 默认端点 os.environ["LANGSMITH_ENDPOINT"] = "https://api.smith.langchain.com" # 或用于自托管 os.environ["LANGSMITH_ENDPOINT"] = "https://your-langsmith-instance.com" ## 追踪问题 ### 追踪信息未显示 **问题**: 追踪的函数未在 LangSmith 中显示。 **解决方案**: 1. **启用追踪**: python import os os.environ["LANGSMITH_TRACING"] = "true" # 验证 print(os.environ.get("LANGSMITH_TRACING")) 2. **检查项目名称**: python import os os.environ["LANGSMITH_PROJECT"] = "my-project" # 或在装饰器中 from langsmith import traceable @traceable(project_name="my-project") def my_function(): pass 3. **刷新挂起的追踪**: python from langsmith import Client client = Client() client.flush() # 等待所有挂起的追踪发送完毕 4. **验证连接**: python from langsmith import Client client = Client() try: projects = list(client.list_projects()) print(f"已连接！发现 {len(projects)} 个项目") except Exception as e: print(f"连接失败: {e}")