LangChain Field Guide

外观

10. 生产化检查清单 ​

模型选择 ​

  • 确认模型支持你的核心能力：聊天、工具调用、结构化输出、长上下文或多模态。
  • 为延迟、成本、稳定性和回答质量设定可量化指标。
  • 准备降级策略：主模型不可用时如何切换备用模型或返回可解释错误。
  • 用真实任务样本评估，不只看单轮演示效果。

Tool 安全 ​

  • 每个 tool 都要有清晰输入 schema、权限边界和超时限制。
  • 对写操作、支付、删除、发消息等高风险动作加入确认或审批。
  • 不要把模型生成的参数直接用于 shell、SQL、文件路径或外部 API。
  • 记录 tool call 和 tool output，但要对敏感信息脱敏。

RAG 质量 ​

  • 确认文档来源可信、版本明确，并有更新流程。
  • 检查 chunk 大小、overlap、metadata 和 retriever 的 k 是否适合任务。
  • 记录检索命中的来源，方便定位错误答案来自哪里。
  • 当检索结果不足时，要求模型说明资料不足，而不是编造。

Prompt 管理 ​

  • 把关键 system prompt 纳入版本管理。
  • 明确输出格式、拒答边界、工具使用规则和语言要求。
  • 避免在 prompt 里混入过期业务规则。
  • 对重要 prompt 建立回归样例，修改后重新评估。

可观测性 ​

  • 记录输入、消息历史、模型配置、tool call、tool output、retrieval 和 final answer。
  • 记录错误类型、耗时、重试次数和 token 使用量。
  • 对日志做脱敏和访问控制。
  • 需要团队排障或评估回归时，考虑接入 LangSmith。

依赖和环境 ​

  • 固定 Python、LangChain、LangGraph、Ollama 模型和向量库版本范围。
  • 为 .env 提供示例，并在启动时检查必要配置。
  • 脚本错误要给出友好提示，不要把原始 traceback 当作用户界面。
  • 在 CI 或本地检查中运行编译、单元测试和关键 smoke test。

安全心智 ​

  • 把模型输出当作不可信建议，而不是已验证事实。
  • 把用户输入、检索文档和外部网页都视为可能包含 prompt injection。
  • 最小化保存数据，只保存完成任务真正需要的内容。
  • 对高影响动作采用 human-in-loop、审计日志和可回滚设计。

上线前最小验收 ​

在把 Agent 放到真实用户面前之前，至少完成下面检查：

  • 准备 20 个常见问题和 10 个刁钻问题，手动跑一遍。
  • 记录每次回答是否调用了正确工具。
  • 检查 RAG 回答是否能追溯到来源。
  • 检查工具异常时用户看到的错误是否可理解。
  • 检查日志是否足以复盘一次失败请求。
  • 检查 .env、密钥、本地向量库和缓存目录是否不会被误提交。
  • 检查依赖版本是否固定，换一台机器能否复现。

常见事故来源 ​

  • 工具权限过大：模型一次错误调用就可能造成真实副作用。
  • 检索结果污染：低质量文档进入知识库后，模型会认真引用错误内容。
  • 提示词被覆盖：用户输入诱导模型忽略系统规则。
  • 日志不足：线上出现坏回答后，无法知道模型看到了什么。
  • 评估缺失：只凭几次演示成功就认为 Agent 稳定。
  • 模型替换无测试：换模型后工具调用格式和回答风格都可能变化。

迭代建议 ​

先把 Agent 做窄。一个可靠的小 Agent，通常比一个什么都能做但不可控的大 Agent 更有价值。

推荐迭代顺序：

  1. 先让单个工具稳定。
  2. 再让 Agent 稳定选择这个工具。
  3. 再加入 RAG 或 memory。
  4. 再加入 streaming 和日志。
  5. 最后考虑 LangGraph、人工审核和持久化。

每加一个能力，都要补对应的观测和测试。否则你只是在增加不可解释的复杂度。

风险分级 ​

不是所有 Agent 都需要同样严格的控制。可以按影响范围分级。

低风险：

  • 只回答公开资料。
  • 不调用有副作用的工具。
  • 错误回答不会造成实际损失。

中风险：

  • 查询内部资料。
  • 生成建议供人参考。
  • 调用只读工具，例如搜索、数据库查询、文档检索。

高风险生产操作

高风险：

  • 写数据库。
  • 发邮件、发通知、改配置。
  • 删除文件、执行命令、支付、审批。
  • 影响法律、医疗、金融或安全决策。

风险越高，越不能只靠 prompt 控制。需要权限、确认、审计、回滚和人工介入。

评估集设计 ​

最小评估集应该覆盖：

  • 常见正常问题。
  • 模糊问题。
  • 知识库没有答案的问题。
  • 工具参数边界问题。
  • 恶意或越权请求。
  • 多轮对话中的指代问题。
  • 模型容易编造的问题。

每条样例至少记录：

  • 用户输入。
  • 期望是否调用工具。
  • 期望引用的资料来源。
  • 不允许出现的行为。
  • 可接受答案要点。

评估不是追求一次满分，而是防止你改 prompt、换模型或改工具后悄悄破坏已有能力。

生产环境的最小架构 ​

一个可维护的 Agent 服务通常至少包含：

  • 配置层：模型、工具、检索器、超时、重试参数。
  • 执行层：Agent 或 LangGraph workflow。
  • 工具层：外部 API、数据库、检索器、本地函数。
  • 策略层：权限、风险控制、人工确认。
  • 观测层：trace、日志、指标、错误分类。
  • 评估层：固定样例和回归测试。

教程里的 CLI 示例只覆盖执行层和一部分工具层。真实项目需要逐步补齐其他层，否则很难排查和治理。