跳到主要内容

第 2.16.3 节：把 LangGraph、前端、部署和观测接成端到端系统

LangGraph、前端、部署与观测只有拆成可执行步骤，才容易复核、排错和交接。完成本节后，你应该能够按顺序说明 LangGraph、前端、部署与观测的触发、处理、复核、记录和兜底步骤。

实现步骤或决策流程​

读图重点：上组是用户请求的运行链：入口、工作流、检索、工具和人工协作；下组是治理链：状态、部署、追踪与恢复。两组通过 trace_id 和 workflow_state 对齐。

推荐技术流​

综合项目推荐按“低风险闭环优先、再逐步增强”的技术流推进。

阶段推荐做法为什么
需求发现访谈业务目标、角色、资料、系统、风险和验收防止把一句“做 AI（人工智能）客服”误解成一个聊天框。
资料准备建资料清单、负责人、版本、权限和状态RAG（检索增强生成）效果先取决于资料能不能被信任。
知识链路文档解析、分块、Embedding（嵌入向量）、索引、重排、引用先证明资料问题能被正确回答。
分流链路识别查询意图，区分资料问题、工具问题、高风险问题防止错误路径，例如用知识库回答订单状态。
工具链路先接只读工具，再做低风险写入草稿，最后考虑高风险审批工具调用风险按等级释放。
工作流编排用 LangGraph（智能体状态图框架）管理状态、分支、重试和人工接管多步骤任务不能靠一次模型自由发挥。
前端工作台展示会话、引用、工具计划、审批、转人工、质检和日志让客服能参与，而不是被黑盒回答替代。
部署治理Docker（容器工具）、Nginx（反向代理服务器）、环境变量、密钥、备份、监控从 Demo（演示）进入可运行服务。
可观测性记录 Trace ID（追踪编号）、模型调用、检索结果、工具结果、耗时和成本出错时能定位是资料、检索、模型、工具还是权限问题。
安全发布Guardrail（护栏）、权限、审批、限流、发布检查、回滚确保系统不会越权、泄露或自动执行高风险动作。
商业验收验收问题集、通过标准、培训交接、维护方式项目完成不是“能聊天”，而是双方确认可用边界。

作品集可以先做到“试点版”：资料治理、知识库 RAG、引用、拒答、基础工具计划、前端工作台和日志。商业生产项目再加入多租户、MCP（模型上下文协议）工具生态、复杂审批、监控告警、成本管理和维护流程。

字段契约​

字段契约是综合项目的骨架。没有字段契约，前端、后端、模型调用、工具执行、日志和质检就会各说各话。

本章不写代码，只用表格说明关键字段。实际项目可以把这些字段落到接口、数据库、日志和前端状态里。

综合请求与回答契约​

字段中文含义由谁产生用在哪里验收要求
project_id（项目编号）当前客服 Agent（智能体）项目编号项目配置或后台生成范围、发布、验收和日志同一个项目的资料、工具、验收集能关联。
tenant_id（租户编号）企业或客户组织编号登录系统或租户配置权限过滤、资料隔离、工具隔离不同租户资料和工具不能串用。
session_id（会话编号）一次连续客服会话编号会话系统生成多轮上下文、转人工、质检同一会话能复盘完整上下文。
query_intent（查询意图）系统判断用户问题类型查询理解模块路由到 RAG、工具、人工或普通回答典型问题分流准确，错误分流可纠正。
retrieval_context（检索上下文）检索到的片段、来源、版本、分数、权限RAG 模块生成回答、引用展示、质检复盘关键回答能追溯到片段和资料版本。
tool_plan（工具计划）计划调用哪些工具、为什么调用、风险等级工具计划模块或工作流节点工具卡片、审批、执行日志写入和高风险工具必须进入确认或审批。
workflow_state（工作流状态）当前任务处于哪个节点和状态LangGraph（智能体状态图框架）或工作流服务前端状态、重试、转人工、恢复中断后能知道停在哪里。
approval_status（审批状态）是否待确认、已批准、已拒绝或不需要审批审批模块或人工操作高风险动作、工单、退款、外部联系未批准的高风险动作不能执行。
answer_draft（回答草稿）模型生成但可能需客服确认的回答生成模块前端编辑、人工确认、发送草稿与已发送答案要区分。
citation_refs（引用来源）回答依据的资料、版本、片段和可见范围RAG 模块前端引用、质检、验收关键结论必须有引用，外部展示要按权限过滤。
quality_score（质量评分）系统或质检对回答质量的评分质检模块、规则或人工发布质量、复盘、数据看板低分回答能进入复盘队列。
handoff_required（是否转人工）是否需要人工接管风险规则、工作流或客服操作转人工、工单、会话状态高风险、低依据、用户不满时能触发。
release_version（发布版本）当前系统、资料或策略发布版本发布系统问题追踪、回滚、验收历史回答能对应当时发布版本。
trace_id（追踪编号）一次请求的全链路追踪编号请求入口生成日志、监控、排错、审计任意问题都能用追踪编号复盘。

这张表可以直接作为作品集项目的核心材料。面试官问“你怎么证明这个系统不是黑盒”，你可以从 trace_id（追踪编号）、retrieval_context（检索上下文）、tool_plan（工具计划）、approval_status（审批状态） 和 citation_refs（引用来源） 回答。

资料与知识片段契约​

字段中文含义用途验收要求
document_id（资料编号）一份资料的唯一标识关联原文、版本和引用引用能回到原始资料。
document_title（资料标题）资料名称前端展示和引用说明客服和业务人员能看懂。
source_type（来源类型）PDF（便携式文档格式）、网页、FAQ（常见问题）、历史工单等解析策略和质量评估不同格式能按规则处理。
owner（负责人）谁负责资料准确性出错复盘和更新每份正式资料都有负责人。
version（版本）资料版本引用和冲突处理新旧资料可区分。
visibility（可见范围）外部客户、内部客服、主管、管理员等权限过滤外部用户不能检索内部资料。
status（状态）草稿、待审核、已发布、已失效、索引失败等发布和索引控制只有已发布资料进入正式回答。
chunk_id（分块编号）知识片段编号检索、引用和复盘片段能定位原文位置。
heading_path（标题路径）片段所在章节路径提升引用可读性引用不只是显示文件名。
quality_flags（质量标记）扫描件质量差、表格缺失、冲突疑似等质量控制低质量片段不直接用于高风险回答。

工具与审批契约​

字段中文含义用途验收要求
tool_name（工具名称）要调用的业务工具前端工具卡片和日志客服知道系统要做什么。
tool_purpose（调用目的）为什么需要这个工具审批和复盘不能无理由调用敏感工具。
risk_level（风险等级）只读、低风险写入、高风险动作决定是否审批高风险动作必须人工确认。
required_role（所需角色）谁有权执行权限检查无权限时不能调用。
input_summary（输入摘要）工具输入的业务摘要人工确认审批人能看懂，不需要读技术细节。
tool_result（工具结果）工具返回的业务结果回答生成和日志工具失败要有可理解原因。
idempotency_key（幂等键）防重复执行标识防止重复建单或重复提交重试不会造成重复业务动作。
approval_note（审批说明）审批人的意见审计和复盘高风险动作有审批记录。

发布与验收契约​

字段中文含义用途验收要求
acceptance_case_id（验收用例编号）一条验收问题编号验收问题集能反复测试。
scenario（场景）资料问答、订单查询、退款申请、权限越权等覆盖业务风险成功和失败场景都要有。
expected_behavior（期望行为）系统应该怎么处理验收标准不要求固定字面答案，但要求行为正确。
must_include（必须包含）回答或动作必须包含的要点业务审核关键政策和限制不能漏。
must_not_include（不能包含）不能出现的内容风险控制不出现无依据承诺或内部信息泄露。
pass_result（通过结果）通过、失败、需复测发布门禁未通过用例要有修复记录。
release_gate（发布门禁）是否允许进入试点、生产或回滚发布管理不能只凭感觉上线。

制作步骤​

下面是一条从 0 到可验收试点的制作路线。它适合作为学习项目，也适合作为商业项目的方案骨架。

第一步：做需求访谈和范围确认​

先确认 6 类问题：

  • 业务目标：减少重复咨询、提升新人客服一致性、缩短处理时间，还是增强质检复盘？
  • 使用者：外部客户、一线客服、售后运营、主管、质检还是管理员？
  • 资料范围：产品资料、售后政策、FAQ（常见问题）、话术、培训手册、历史工单分别在哪里？
  • 系统范围：是否接订单、物流、工单、CRM（客户关系管理系统）和统一登录？
  • 自动化边界：哪些只生成草稿，哪些可以自动执行，哪些必须人工确认？
  • 验收方式：用哪些场景、问题集和日志证明系统可用？

不要在这些问题没回答之前讨论模型参数。模型只是实现手段，不是项目范围。

第二步：建立资料台账和治理规则​

给每份资料建立资料台账：标题、来源、负责人、版本、状态、可见范围、生效时间、失效时间和质量标记。

资料状态建议至少包含：

状态是否进入正式回答说明
草稿否未审核资料不能作为企业承诺。
待审核否业务负责人还没确认。
已发布是可进入正式索引和回答。
需更新视规则可以提示风险或暂时降权。
已失效否只能保留审计，不用于新回答。
索引失败否需要修复解析或分块。

资料治理是综合项目的地基。地基不清，后面调再多模型也没有意义。

第三步：设计文档解析和标准中间格式​

文档解析要解决“原始资料如何变成可处理内容”。你不需要在本章写解析代码，但要定义解析输出应该包含什么：

  • 正文内容。
  • 标题层级。
  • 表格内容。
  • 图片或附件说明。
  • 原文位置。
  • 资料版本。
  • 可见范围。
  • 解析质量标记。

解析结果必须能追溯回原文。否则用户问“依据在哪里”，系统只能说“来自某个文件”，这不够验收。

第四步：设计分块、Embedding（嵌入向量）、索引和重排​

分块不是随便按字数切。客服资料里，售后政策、产品参数、FAQ（常见问题）和投诉流程的结构不同，分块策略也不同。

推荐原则：

  • 分块要保留标题路径和资料版本。
  • 一个片段尽量包含完整业务结论。
  • 表格资料要保留列名和行含义。
  • 旧版本和新版本不能混成一个片段。
  • 外部可见和内部可见资料不能混在同一个检索范围。
  • 检索后要做重排和阈值判断。
  • 低置信度、冲突和无引用要拒答或转人工。

索引完成后，不要只问一句“能不能答”。要用验收问题集检查命中、引用、拒答和权限。

第五步：设计查询意图识别和路由​

综合 Agent 不能把所有问题都丢给同一条链路。

查询意图示例推荐路径
企业资料问答“A 产品保修多久？”RAG。
业务状态查询“我的订单到哪了？”工具调用。
写入动作“帮我建个投诉工单。”工具计划 + 人工确认或低风险执行。
高风险争议“你们必须赔我多少钱？”转人工或审批。
通用解释“什么是保修？”普通回答或引导到企业政策。
权限敏感“内部补偿规则是什么？”权限检查，不可见则拒答。

这一步会产生 query_intent（查询意图）。后面所有模块都依赖它，所以分流结果要写入日志，便于纠错。

第六步：设计 RAG（检索增强生成）回答链路​

RAG 链路至少包含 7 个动作：

  1. 根据租户和角色确定可检索资料范围。
  2. 根据查询意图生成检索请求。
  3. 召回候选片段。
  4. 重排并过滤低质量片段。
  5. 判断资料是否足够、是否冲突、是否过期。
  6. 生成 answer_draft（回答草稿） 和 citation_refs（引用来源）。
  7. 根据风险决定直接展示、客服确认、拒答或转人工。

这里的关键不是让回答更长，而是让回答有依据、有边界、有引用。

第七步：设计工具调用和 MCP（模型上下文协议）接入​

工具链路要先分级：

工具类型示例处理方式
只读查询查订单、查物流、查工单状态有权限可直接执行，记录日志。
低风险写入创建工单草稿、添加备注可生成草稿，必要时客服确认。
高风险动作退款、发券、外部联系、关闭投诉必须审批，不允许模型直接执行。
管理工具修改资料状态、发布索引、调整权限仅管理员可用，并记录审计。

当工具数量多、客户端多、需要复用时，可以把工具能力通过 MCP 组织起来。MCP 解决“工具如何标准化暴露”，但不解决“谁可以调用、何时审批、失败如何兜底”。这些仍然要由业务系统设计。

第八步：用 LangGraph（智能体状态图框架）组织工作流​

当流程变成多步骤，就需要显式状态。

一个退款咨询可能这样流转：

  1. 识别用户问题为退款相关。
  2. 检索退款政策。
  3. 调用订单工具查询订单状态。
  4. 判断是否满足基础条件。
  5. 生成客服回复草稿。
  6. 如果用户要求提交申请，生成工单草稿。
  7. 等待客服确认。
  8. 记录结果和质检信息。

每一步都要写入 workflow_state（工作流状态）。失败时要知道是检索失败、工具失败、审批未通过，还是用户需要补充信息。

第九步：决定是否需要多智能体​

多智能体适合职责差异明显的场景。例如：

  • Router（路由）智能体：判断查询意图和风险。
  • Knowledge（知识）智能体：处理资料检索和引用。
  • Tool（工具）智能体：生成工具计划并检查权限。
  • Ticket（工单）智能体：整理工单草稿和转人工信息。
  • QA（质检）智能体：复盘回答质量和引用准确性。

如果项目还很小，一个主流程足够，不要为了“多智能体”而拆。拆分后必须有交接字段、主控规则和日志。否则系统会更难调试。

第十步：设计前端工作台​

前端不是把聊天结果显示出来就结束。客服工作台至少要有这些区域：

区域展示内容作用
会话区用户问题、系统草稿、客服确认、历史上下文让客服理解当前对话。
引用区资料标题、版本、片段摘要、可见范围让客服验证依据。
工具区工具计划、输入摘要、风险等级、执行结果让客服知道系统准备做什么。
审批区待确认动作、审批状态、审批说明控制高风险动作。
转人工区转人工原因、建议处理人、工单摘要支持接管。
质检区质量评分、用户反馈、问题标签支持复盘。
日志区trace_id（追踪编号）、发布版本、耗时、错误支持排错。

面试时，你可以强调：工作台不是为了好看，而是为了让 AI 的建议可检查、可修改、可接管。

第十一步：部署、可观测性和成本控制​

试点版也要考虑运行问题。最低要求包括：

  • 环境隔离：开发、测试、生产配置分开。
  • 密钥管理：模型密钥、数据库密码、工具凭证不写进页面或文档。
  • 健康检查：知道 API（应用程序接口）、向量数据库、工具服务是否可用。
  • 日志追踪：每次请求有 trace_id（追踪编号）。
  • 成本记录：模型调用、Embedding（嵌入向量）、重排、工具耗时可见。
  • 限流策略：防止异常请求拖垮服务或费用失控。
  • 备份和回滚：资料、索引、配置和发布版本可以恢复。

部署不是最后一天才想的事。字段契约、日志和发布版本从一开始就要留位置。

第十二步：设计安全、发布质量和商业验收​

发布前要跑验收问题集，而不是靠开发者自己试几句。

验收至少覆盖：

  • 正常资料问答。
  • 无资料拒答。
  • 资料冲突。
  • 过期资料。
  • 外部用户越权问题。
  • 内部客服资料问题。
  • 订单查询工具。
  • 工单草稿工具。
  • 高风险退款或补偿。
  • 转人工。
  • 工具失败。
  • 发布回归。

商业验收还要确认培训、交接、维护和变更流程。否则客户会把后续新增需求继续当成“没做完”。

和后续章节关系​

本章是第 2 卷工程实战篇的收束章，因此它和“后续章节”的关系不是继续展开某个技术细节，而是把读者带到第 3 卷行业迁移和求职作品集。

后续内容本章提供什么基础
第 3 卷行业案例用本章的制作路线迁移到电商、教育、医疗、企业内训、销售支持等行业。
50 个项目案例每个项目都可以套用需求、资料、工具、权限、验收和风险拆解。
作品集项目本章提供主项目讲法和追问回答框架。
求职面试模块把技术能力讲成业务目标、系统方案、验收标准和复盘能力。
商业接单把一句需求拆成范围、报价、里程碑、验收和维护。

如果第 2 卷前面章节是“零件”，本章就是“装配说明和验收总图”。

版本与资料来源​

本章是工程实战篇收束章，不提供完整源码，不讲 Python（编程语言）、TypeScript（类型化脚本语言）、JavaScript（脚本语言）或 JSON（结构化数据格式）语法，重点讲综合知识库 Agent 的制作路线、字段契约、系统边界、失败兜底、发布质量和面试表达。

资料依据：

过时风险：模型能力、Embedding（嵌入向量）模型、向量数据库、MCP 生态、LangGraph（智能体状态图框架）接口、云部署方式和安全合规要求都会变化。进入真实项目开发或商业交付前，必须重新核对当前官方文档、客户系统权限、资料授权、模型成本和行业合规要求。

继续学习​