PyLLM

主题

9.1 项目概述与需求分析 ​

经过前8章的系统学习，我们已经掌握了 LangGraph 的所有核心概念：状态管理、节点编程、边路由、人机协作（Interrupt）、循环迭代、子图模块化、持久化Checkpointing、以及多Agent协作。现在是时候把这些知识综合运用到一个完整的项目中了。本章和下一章我们将分别构建两个完整的实战项目——智能客服工单系统和自主研究助手Agent。这两个项目会覆盖从需求分析到架构设计、从核心实现到部署优化的完整开发生命周期，让你看到 LangGraph 在真实场景中是如何发挥威力的。

项目背景与业务场景 ​

想象你是一家中型互联网公司的技术负责人，公司目前的客服体系面临以下痛点：

现状问题：

  1. 客服团队每天收到 500+ 条用户咨询，其中大量是重复性问题（"怎么重置密码"、"如何退款"、"API 调用报错"）
  2. 工单处理流程混乱——简单问题也要走完"接收→分类→分配→处理→回复"的全流程
  3. 高优先级工单（如支付失败、账户异常）没有快速通道，和普通咨询排队等待
  4. 客服人员的回复质量参差不齐，缺乏统一的知识库支撑
  5. 没有数据驱动的改进机制，不知道哪些类型的问题最多、哪些客服效率最低

期望目标： 构建一个智能客服工单系统，能够自动完成以下工作：

  • 接收用户消息并自动分类（技术咨询/账务查询/投诉建议/其他）
  • 对常见问题自动匹配知识库答案并直接回复
  • 对复杂问题自动收集信息、分级路由到对应处理人
  • 高优先级工单走加急通道并通知相关人员
  • 全程记录操作日志，支持人工审核关键决策点
  • 提供数据分析面板帮助持续优化

需求分析与功能分解 ​

基于上述背景，我们可以把系统需求分解为以下功能模块：

FR-1：消息接入与预处理 ​

  • 支持多种输入渠道（文本/图片/语音转文字）
  • 自动去除噪声（去重、标准化格式、敏感词检测）
  • 提取关键实体（订单号/用户ID/错误码等）

FR-2：智能分类与路由 ​

  • 多维度分类：按问题类型 / 紧急程度 / 用户等级 / 历史行为
  • 规则引擎处理明确模式 + LLM 处理模糊语义
  • 四级路由：自动解决 / 一线客服 / 技术专家 / 经理审批

FR-3：知识库自动应答 ​

  • FAQ 匹配：关键词 → 标准答案模板
  • 语义搜索：用户描述 → 向量检索最相关文档
  • LLM 增强：检索结果 → 自然语言生成个性化回复

FR-4：复杂工单的完整生命周期 ​

  • 信息收集 → 初步诊断 → 尝试自动修复 → 人工审核 → 执行 → 回访确认
  • 每个环节都有状态追踪和时间戳
  • 支持 Interrupt 在关键节点暂停等待人类确认

FR-5：运营监控与分析 ​

  • 实时仪表盘：当前工单数、平均处理时间、各队列积压量
  • 分类统计：问题类型分布、解决率、满意度趋势
  • 客服绩效：每个客服处理的工单量和质量评分
  • SLA 达标率监控

非功能需求 (NFR) ​

  • NFR-1 性能：自动分类响应 < 2 秒；知识库匹配 < 1 秒
  • NFR-2 可用性：系统可用性 ≥ 99.9%（支持多实例部署）
  • NFR-3 安全：所有操作有审计日志；敏感操作需二次确认
  • NFR-4 可扩展性：支持水平扩展以应对流量峰值

技术架构设计 ​

整体架构概览 ​

┌─────────────────────────────────────────────────────┐
│                  API Gateway (FastAPI)                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ Web 前端   │  │ 移动端    │  │ 第三方    │        │
│  └──────────┘  └──────────┘  └──────────┘        │
└─────────────────────┬─────────────────────────────┘
                    │ HTTP/SSE
                    ▼
┌─────────────────────────────────────────────────────┐
│              LangGraph Application                 │
│                                                   │
│  ┌──────────────────────────────────────────┐       │
│  │           Ticket Processing Graph          │       │
│  │                                           │       │
│  │  [receive] → [classify] → [route]      │       │
│  │      ↓              ↓         ↓              │       │
│  │  [auto_reply] [assign]  [escalate]     │       │
│  │      ↓              ↓                   │       │
│  │  [confirm]  [execute]  [human_review]   │       │
│  │                                           │       │
│  └──────────────────────────────────────────┘       │
│                                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ Qdrant   │  │ PostgreSQL│  │ Redis    │        │
│  │ (向量库) │  │ (工单DB)  │  │ (缓存)   │        │
│  └──────────┘  └──────────┘  └──────────┘        │
└───────────────────────────────────────────────────┘

图拓扑结构设计 ​

系统的核心是一个 LangGraph StateGraph，其内部结构如下：

                    [START]
                       │
                       ↓
               [preprocess_message]
               (消息预处理)
                       │
                       ↓
              [classify_intent]
         (意图分类: 规则+LLM)
                       │
            ┌────────────┼────────────┐
            ↓            ↓            ↓
     [auto_resolve]  [route_normal] [route_urgent]
     (知识库匹配)   (常规路由)     (加急路由)
            │            │            │
            ↓            ↓            ↓
     [send_reply]  [assign_agent] [notify_mgr]
            │            │            │
            ↓            ↓            ↓
          [END]    [await_confirm] [await_approve]
                           │ (Interrupt)
                           ↓
                      [execute_resolution]
                           ↓
                         [follow_up_check]
                           ↓
                          [END]

这个拓扑涵盖了前面章节讨论过的几乎所有核心模式：

  • 条件路由（classify_intent 后的三路分支）
  • 并行可能（auto_resolve 和 route_normal/route_urgent 可以视为不同分支）
  • Interrupt 人机协作（await_confirm / await_approve 的审核节点）
  • 循环/回退（如果执行失败可以回到 assign_agent 重试）

项目目录结构与里程碑计划 ​

project_root/
├── docs/pages/llm/langgraph/
│   ├── 09-01-project-overview-and-requirements.md  ← 本章文件
│   ├── 09-02-core-module-implementation.md
│   ├── 09-03-api-and-frontend.md
│   ├── 09-04-deployment-and-optimization.md
│   └── 09-05-monitoring-and-analytics.md
│
├── src/
│   ├── graph/
│   │   ├── __init__.py
│   │   ├── state.py              # 所有状态定义
│   │   ├── nodes/
│   │   │   ├── receive.py
│   │   │   ├── preprocess.py
│   │   │   ├── classify.py
│   │   │   ├── knowledge_base.py
│   │   │   ├── auto_resolve.py
│   │   │   ├── router.py
│   │   │   ├── assign.py
│   │   │   ├── execute.py
│   │   │   ├── follow_up.py
│   │   │   └── notify.py
│   │   └── ticket_graph.py        # 主图定义
│   ├── services/
│   │   ├── kb_service.py          # 知识库服务
│   │   ├── notification_service.py # 通知服务
│   │   └── analytics_service.py    # 分析服务
│   └── config.py
│
├── tests/
│   ├── test_classify.py
│   ├── test_kb_match.py
│   ├── test_full_pipeline.py
│   └── test_integration.py
│
├── docker-compose.yml
├── Dockerfile
└── README.md

里程碑计划 ​

阶段时间交付物
M1: 架构设计与状态定义第9章第2节State 类型、图拓扑、接口定义
M2: 核心模块实现第9章第3节所有节点函数、主图编译
M3: API 与前端集成第9章第4节FastAPI 接口、前端页面
M4: 部署与优化第9章第5节Docker、监控、性能调优
M5: 测试与验收补充测试完整测试套件、端到端验证

从这里出发 ​

接下来的四个小节将逐步实现这个智能客服工单系统的各个部分。我们会先设计和实现核心的状态结构和图拓扑（第2节），然后构建 API 服务层和模拟前端（第3节），接着讨论生产部署方案（第4节），最后建立运营监控体系（第5节）。每一步都会综合运用前面8章学到的 LangGraph 知识，让你看到一个真实的、可运行的完整系统是如何一步步构建起来的。

基于 MIT 许可发布

版权所有 © 2024-至今