Chat LangChain 生产部署三步避坑指南

Chat LangChain 生产部署三步避坑指南【免费下载链接】chat-langchain项目地址: https://gitcode.com/GitHub_Trending/ch/chat-langchainChat LangChain 是一个基于 Managed Deep AgentMDA部署的文档问答系统后端是 Python Agent前端是 Next.js 聊天界面。本文按上线时间线讲生产环境配置先把环境变量分组配全再用最小命令完成启动最后按优先级盯住监控指标。 上线前环境变量怎么分组配所有配置项都集中在 .env.example 里照它建一份.env即可但建议按下面三组来核对每组漏配的表现都不一样好排查。分组关键变量漏配后的典型后果存储层SUPABASE_URLSUPABASE_*_ANON_KEYus / eu / apac / aws 四区域、MDA_GUEST_SIGNING_KEY注册登录与游客guest会话校验直接失败多区域路由错乱会话状态串区模型服务ANTHROPIC_API_KEY、OPENAI_API_KEY、GOOGLE_API_KEY、BASETEN_API_KEY至少其一PYLON_API_KEYPYLON_KB_IDLANGCHAIN_TRACING_V2trueLANGSMITH_API_KEYLANGSMITH_PROJECT默认模型初始化直接报错、回退链fallback chain断掉知识库搜索工具空转LangSmith 没有 trace出问题时无线上证据运行时LANGGRAPH_AUTH_SECRETNEXT_PUBLIC_LANGGRAPH_AUTH_KEY两端必须一致、MODEL_MAX_RETRIES、USE_LOCAL_PROMPTS、前端PORT/NODE_ENV前后端共享密钥不一致请求在网关层被拒NODE_ENV没设 production 时 Next.js 以开发模式跑白白多吃资源这组变量最容易被漏的是模型服务组里的回退链src/agent/config.py里默认模型走 Google回退依次是 GPT 和 Claude只配一个 Key 时回退链等于摆设建议至少配两家。另外说明一句本仓库的会话 checkpointer、缓存都由 MDA 托管运行时接管如果你改为自托管状态存储则还需要补DATABASE_URL、REDIS_URL、向量库连接这类变量这一组不能跳。 上线时最小启动命令怎么写后端不需要自己写 HTTP 服务和 DockerfileMDA 托管运行时负责入口、身份校验和 checkpointer仓库入口是 agent.py依赖清单见 pyproject.toml。构建并部署两条命令cp .env.example .env # 填入模型 Key、Pylon、LangSmith、Supabase 等值 uv run mda deploy . # 构建并部署后端 Agent会预检 GOOGLE_API_KEY前端在本地完成构建后以生产模式跑并指向后端的 MDA 部署地址NEXT_PUBLIC_LANGGRAPH_API_URL模板见frontend/.env.local.examplecd frontend npm ci npm run build npm start # NODE_ENV 为 production接入前面配好的 Supabase 登录启动阶段就做一次冒烟发一条 LangChain 相关问题和一条明显跑题的问题前者应触发文档搜索后者应被护栏GuardrailsMiddleware拦截。 上线后监控指标按什么顺序盯按响应与错误 → 资源 → 业务的优先级排前一层稳定了再看后一层。响应与错误最先看盯端到端首字延迟建议看 P95和 5xx 比例。这个系统有两层内置重试——模型重试ModelRetryMiddleware次数由MODEL_MAX_RETRIES控制和工具重试ToolRetryMiddleware最多 3 次它们消化掉大部分抖动所以告警不要对单次失败敏感。资源Agent 进程 CPU / 内存、前端 Node 进程、Supabase 各区域连接数。长会话会触发摘要中间件13 万 token 触发、保留 3 万上下文膨胀时摘要调用量上升这是内存和延迟异常的常见信号。业务护栏拦截率突增说明流量里混入了大量跑题输入用户反馈经 connectors/langsmith.py 代理回传到 LangSmithLANGSMITH_PROJECTdocs-agent负反馈占比是最直接的对话质量指标guest 与注册用户比例可用于观察登录链路是否劣化。告警思路不绑具体产品每个指标配阈值 持续时间如 P95 首字 5 秒且持续 10 分钟再触发避免抖动报警同一根因的告警要能归并否则一次模型侧故障会刷满你的通知渠道。日志层面保持 INFO 即可排查时靠 LangSmith 的 trace 元数据build_docs_agent_trace_metadata写入根 trace把前端一次提问和后端整条执行链关联起来。️ 保底线密钥轮换与排查入口密钥轮换模型 Key、SUPABASE_*_ANON_KEY、MDA_GUEST_SIGNING_KEY、LANGSMITH_API_KEY定期轮换注意LANGSMITH_API_KEY只在服务端使用前端对 LangSmith 的操作全部走代理浏览器拿不到它。传输与访问控制前端必须走 HTTPSLANGGRAPH_AUTH_SECRET两端一致且定期更换游客令牌有效期 24 小时见identity.py不要调长。最小暴露.env不进代码仓库前端NEXT_PUBLIC_*变量会打进浏览器包只放 anon 级的公开值。出问题去哪查按顺序走这三个入口模型或中间件行为异常看src/agent/config.py的MODELS与API_KEYS启动日志会逐个打印{key} configured缺哪条一目了然。登录 / 游客会话异常核对.env里对应区域的SUPABASE_URL/SUPABASE_*_ANON_KEY是否齐全区域标签x-supabase-region与变量前缀是否对得上。护栏与重试策略是否符合预期跑评估用例复现线上行为uv run pytest tests/evals -q # 护栏范围、重复搜索、重试接线等评估下一步动作把.env三组值填齐本地uv run mda dev .跑通冒烟后执行mda deploy当天把首字延迟和 5xx 两条告警阈值配好。【免费下载链接】chat-langchain项目地址: https://gitcode.com/GitHub_Trending/ch/chat-langchain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考