1. 异步编程与事件循环管理
关键概念
- 事件循环检测 ：
asyncio.get_event_loop().is_running()判断运行环境 - 多环境兼容：同时支持 Jupyter（已有事件循环）和脚本（标准环境）执行
- 资源生命周期 ：使用
async with确保异步客户端正确初始化和清理
实践要点
- 在同步函数中调用异步代码需谨慎处理事件循环
- 避免在已有事件循环中使用
asyncio.run() - 使用
ensure_future()+run_until_complete()处理嵌套异步调用
2. 并发控制与线程安全
关键概念
- 并发限制 ：使用
asyncio.Semaphore(n)控制最大并发数 - 线程安全问题：共享状态对象（如检索引擎）通常非线程安全
- 资源保护 ：使用
threading.Lock()保护共享资源
实践要点
- 服务器端共享资源必须加锁保护
- 客户端应根据服务器能力调整并发策略
- 串行处理是调试并发问题的有效手段
3. 数据类型与序列化
关键概念
- 类型一致性：工具函数参数类型必须与调用时传递的类型严格匹配
- JSON序列化：复杂对象需转换为字符串格式才能嵌入提示词
- 安全序列化 ：
json.dumps(obj, ensure_ascii=False, indent=2)保持可读性
实践要点
- 提示词中只能插入字符串，不能直接插入字典对象
- 工具函数定义的参数类型决定调用方式
- 注意 JSON 解析异常处理
4. 错误处理与调试策略
关键概念
- 分层异常处理：网络层、业务层、应用层分别处理不同类型错误
- 详细日志 ：使用
traceback.print_exc()获取完整错误堆栈 - 健康检查 ：实现
/health端点验证服务可用性
实践要点
- 客户端应处理网络超时、HTTP错误、解析错误等场景
- 服务器端应捕获业务异常并返回标准化错误信息
- 从串行到并发的渐进式测试策略
5. FastAPI 服务开发模式
关键概念
- 生命周期管理 ：
lifespan事件处理资源初始化和清理 - 请求/响应模型：使用 Pydantic BaseModel 定义接口契约
- 线程池集成 ：
loop.run_in_executor()执行阻塞操作
实践要点
- 全局状态对象需考虑线程安全
- 阻塞操作应在独立线程中执行避免阻塞事件循环
- 使用类型注解提高代码可维护性
6. LangChain 工具开发范式
关键概念
- 工具装饰器 ：
@tool将普通函数转换为可调用工具 - 参数验证：工具函数参数类型决定调用接口
- 返回规范：工具应返回字符串而非复杂对象
实践要点
- 工具函数应专注于单一职责
- 提示词设计需明确角色、技能、约束条件
- 工具调用需确保参数类型和名称完全匹配
7. RAG 系统集成模式
关键概念
- 文档范围限定：通过文档名和跳数参数控制检索范围
- 多轮检索：基于第一轮结果分析生成补充查询
- 结果结构化：标准化响应格式便于后续处理
实践要点
- 检索问题应避免包含具体数值，保持通用性
- 系统应能识别"未规定"等无效答案并触发深入查询
- 问答流程应支持失败回退和重试机制
8. 性能优化策略
关键概念
- 请求节流：在连续请求间添加小延迟避免服务器压力
- 连接复用：使用同一个客户端实例处理多个请求
- 超时设置：合理配置网络请求超时时间
实践要点
- 并发数应根据服务器处理能力调整
- 长时间运行的请求应提供进度反馈
- 资源密集型操作应考虑缓存策略
9. 开发调试方法论
关键概念
- 分步验证：逐个组件单独测试再集成
- 日志分级：使用不同日志级别控制输出详细程度
- 输入输出追踪：记录关键步骤的输入输出便于问题定位
实践要点
- 先确保单请求正常工作再测试并发
- 使用简单测试用例验证复杂逻辑
- 保持接口契约的稳定性