智能客服 Agent

智能客服系统：文档知识库 + 混合检索问答 + LangGraph 客服编排（意图识别 / 澄清 / 转人工）+ 会话与文档云端持久化。 两条主链路：入库（解析→切块→向量）、问答（检索→rerank→生成→引用校验）；两条门禁：57 条业务评测 + 13 条红队攻击语料。

系统分层架构

flowchart TB
    subgraph Browser["浏览器 · Vite dev :5173"]
        KP["KnowledgePanel<br/>上传 / 文档列表 / chunk 数"]
        CS["ConversationSidebar<br/>真实会话列表"]
        CP["ChatPanel<br/>Bubble.List + AnswerView"]
    end

    subgraph Server["server 包 · uvicorn :8000"]
        MAIN["main.py · 应用工厂<br/>CORS + 路由 + lifespan"]
        API["api/<br/>health · docs · ingest · ask · conversations"]
        AUTH["auth/<br/>JWT + operator/customer 角色"]
        SVC["services/<br/>rag 融合 · customer_service<br/>chat_store · doc_store<br/>限流 / 熔断 / 审计 / 脱敏"]
        TOOLS["tools/<br/>订单/物流只读 + Pydantic 校验"]
        GRAPH["graph/<br/>rag 图 + customer_service 图"]
        CORE["core/<br/>解析 → 切块 → 向量<br/>检索 → rerank → 生成 → 引用"]
    end

    subgraph Storage["存储"]
        QD["Qdrant local<br/>server/qdrant_data<br/>单进程锁 + --workers 1"]
        MY["MySQL<br/>会话 / 消息 / 文档切块<br/>公网直连 · 零 Redis 依赖"]
    end

    subgraph AI["AI 服务"]
        EMB["远程 Embeddings<br/>EMBED_BASE_URL"]
        LLM["DeepSeek<br/>chat / 生成 / 意图"]
        RR["硅基流动<br/>bge-reranker-v2-m3"]
    end

    KP -->|fetch| API
    CS --> API
    CP -->|SSE| API
    API --> SVC
    API --> GRAPH
    SVC --> CORE
    GRAPH --> TOOLS
    SVC --> MY
    CORE --> QD
    CORE --> EMB
    CORE --> LLM
    CORE --> RR
    GRAPH --> LLM
    GRAPH --> SVC

    style CORE fill:#ffe6cc,stroke:#d79b00
    style GRAPH fill:#dae8fc,stroke:#6c8ebf

链路时序

入库（文件 → 向量库）

sequenceDiagram
    autonumber
    participant U as 用户
    participant FE as KnowledgePanel
    participant API as /api/ingest
    participant PR as 解析层<br/>(MinerU→markitdown→纯文本)
    participant CH as 结构感知切块
    participant EMB as Embeddings
    participant QD as Qdrant
    participant DB as MySQL

    U->>FE: 拖拽上传 PDF/MD/DOCX
    FE->>API: POST /api/ingest (multipart)
    API->>API: 防路径穿越 + 扩展名白名单
    API->>PR: 解析 (sha256 缓存)
    PR-->>API: 结构化文本 + 标题路径
    API->>CH: 按标题层级/段落边界聚合
    CH-->>API: chunk[] + 元数据
    API->>EMB: 向量化
    EMB-->>API: vectors[]
    API->>QD: upsert (point_id = sha1(chunk_id))
    API->>DB: 存切块 + 元数据
    DB-->>API: ok
    API-->>FE: 200 {doc_id, chunks}
    FE-->>U: 知识库新增成功

问答（Query → 引用校验）

sequenceDiagram
    autonumber
    participant U as 用户
    participant FE as ChatPanel
    participant API as /api/ask
    participant RT as 混合检索<br/>(BM25 + Vector RRF)
    participant RR as Rerank
    participant LLM as DeepSeek
    participant V as 引用校验

    U->>FE: 提问
    FE->>API: POST /api/ask {query, session_id}
    API->>RT: 双路召回
    RT-->>API: candidates[]
    API->>RR: rerank (top-k 精排)
    RR-->>API: ranked[]
    API->>LLM: 生成 (强制 [来源N])
    LLM-->>API: answer
    API->>V: 程序校验越界引用
    V-->>API: {answer, citations, valid}
    API-->>FE: SSE 流式返回
    FE-->>U: 气泡 + 引用卡片

核心能力

API 概览（demo curl）

# 入库
curl -F "file=@doc.pdf" -F "session_id=demo" http://127.0.0.1:8000/api/ingest

# 知识问答（SSE 流式）
curl -N -X POST http://127.0.0.1:8000/api/ask \
  -H 'Content-Type: application/json' \
  -d '{"query":"什么是 AI Agent？","session_id":"demo","top_k":5}'

# 列出文档
curl http://127.0.0.1:8000/api/docs

# 健康检查
curl http://127.0.0.1:8000/api/health

# Prometheus 指标
curl http://127.0.0.1:8000/metrics

完整 API（请求/响应/错误码/curl 实测）见 docs/api.md。

RAG 关键踩坑实录（P0 优先级）

1. 解析三级降级 + sha256 缓存：MinerU 云解析 → markitdown → 纯文本兜底；按内容 sha256 缓存，避免重跑。
2. 结构感知切块而非硬切：标题路径和段落边界进入 chunk 元数据、embedding 上下文与 Prompt；chunk_size 仅为目标，不硬切段落——超长段落保持完整。
3. RRF 倒数排名融合：标题加权 BM25（中文 2-gram + 英文词）与语义向量双路召回 → 倒数融合，而非加权求和（不同尺度的得分不能直接相加）。
4. 引用强制 + 程序校验：Prompt 强制 [来源N]；生成后程序扫描越界引用，前端「引用校验通过/含越界引用」徽标 + 素材原文展开。
5. rerank 失败静默回退：rerank 超时/出错时直接用向量检索 top-k 继续生成，不阻塞前端，避免单点失败拖垮整轮问答。
6. Qdrant 单进程锁：与生产远端同 API；本地用 threading.Lock + --workers 1 避免并发写索引崩溃。
7. MySQL 重启重建向量：文档切块存 MySQL，服务启动 lifespan 检测到 Qdrant 空索引时自动重建——重新部署不丢数据。

安全与健壮性

安全（P0 红队阻断率 = 1.0）

• 上传：防路径穿越（只取 basename）、扩展名白名单、密钥只存本地/环境变量（均不入库）
• PII 三层脱敏：手机号/身份证/邮箱/银行卡/订单号——Prompt 组装脱敏 + 指标埋点脱敏 + SSE 响应脱敏（用户层面也能拿到无 PII 文本）
• 限流 429：固定窗口原子计数（MySQL 实现，零 Redis 依赖）
• 熔断：closed/open/half-open 状态机
• 审计日志：trace_id 关联，全 MySQL 实现
• 红队门禁：13 条攻击语料（提示注入 6 / 越权 2 / 对抗样本 5）逐题断言「被阻断/不泄露」——实测 redteam_block_rate = 1.0，接入 GitHub Actions CI

红队三类攻击与防线

健壮性（优雅降级）

• LangGraph 不可用 → 回退 RAG 直答
• MySQL 不可用 → 回退内存仓储，响应体带 storage: "memory" 显性标注
• 空库 → 友好回答 + 客服层二次澄清后转人工，不报错
• LLM 超时 → 重试 + 失败转人工
• rerank 失败 → 静默回退向量 top-k（已记录）

评测与监控

业务指标埋点（每轮对话记录）

Prometheus 暴露（GET /metrics）

cs_eval_handoff_rate{session}             # 转人工率
cs_eval_error_rate{session}               # 出错率
cs_eval_unfounded_rate{session}           # 无依据承诺率
cs_eval_first_resolution_rate{session}    # 一次解决率
cs_eval_tool_success_rate{tool}           # 工具成功率
cs_eval_latency_ms_bucket{le="..."}       # 响应时延直方图

离线评测（接入 CI）

# 客服任务离线评测（意图/工具/转人工/越权/槽位）
.venv/bin/python -m server.cli cs-eval --fail-under 0.9

# 联动检索评测（Recall@K / MRR，需向量库）
.venv/bin/python -m server.cli cs-eval --with-retrieval

# 红队安全门禁
.venv/bin/python -m server.cli cs-redteam --fail-under 0.9

# JSON 报告（CI 用）
.venv/bin/python -m server.cli cs-eval --json --fail-under 0.9

实测：Recall@1/3/5 = 1.0、MRR = 1.0、redteam_block_rate = 1.0、cs-eval 通过率 ≥ 0.9。

告警阈值（可配）

告警落 evaluation_alerts 表 + 可选 webhook（ALERT_WEBHOOK_URL）。

关键设计决策

1. 单一后端包 + src 布局：rag/langgraph/api 三层合并为 server 包，正规 from server.core.retrieve import retrieve 导入（无 sys.path hack、无模块名碰撞），依赖单一来源 server/pyproject.toml
2. 编排与检索解耦：LangGraph 图全部依赖注入（retriever/generator/classifier 参数化），契约测试不碰向量库与模型——离线评测可以完全 mock
3. 可替换意图分类器：规则/LLM 分类器同契约（{intent, intent_confidence, slots}），LLM 低置信度自适应追问、失败自动回退规则；规则层支持多意图风险仲裁（投诉>售后>订单>寒暄）；LLM_CLASSIFIER=1 一键切换
4. MySQL 而非 Redis：限流/熔断/审计全 MySQL 实现，零 Redis 依赖——降低运维复杂度与成本，云端部署更轻
5. SSE 而非 WebSocket：服务端业务日志（INFO 起）统一输出到 stdout，每行自动带当前请求的 trace_id，格式 2026-09-06 15:42:00 INFO [a1b2c3...] server.services.customer_service: 客服消息收到 ...，从日志按 trace_id 即可串起一轮对话全链路

迭代路线

完整文档索引