跳到主要内容

React RAG 与产品化（第 5-8 周）

目标：完成 RAG Demo，并补齐成本/可观测能力。

目录​

任务清单​

  • 文档切分 + 引用面板
  • 多模型切换
  • 成本面板 + traceId

后端最小接口建议​

  • POST /rag/search：返回证据
  • POST /rag/answer：返回答案 + 引用
  • GET /metrics：返回 token 统计

最小可运行代码​

setCitations(["S1", "S2"]);
setTraceId("trace-xxxx");

引用面板组件（最小版）​

function CitationPanel({ items }) {
  return (
    <ul>
      {items.map((c) => (
        <li key={c.id}>{c.title}</li>
      ))}
    </ul>
  );
}

项目结构​

rag-demo/
  web/
    components/
      CitationPanel.tsx
      CostPanel.tsx

验收标准​

  • 引用面板可展开
  • 成本面板可查看

详细解析：RAG 在前端的落地​

引用面板交互​

  • 默认折叠
  • 点击展开显示 chunk
  • 支持复制

成本面板要素​

  • 每日 token 使用量
  • 单次请求上限
  • 预算告警提示

Mermaid：RAG 前端交互流程​

调试建议​

  • 校验引用编号与证据一致
  • 记录 cost 与异常类型
  • 确保 TopK 可配置

详细步骤（第 5-8 周）​

  1. 先做 RAG 闭环
  2. 加引用面板
  3. 加成本面板
  4. 加 traceId 与错误码

引用面板数据结构​

type Citation = { id: string; title: string; page?: number };

成本面板最小字段​

  • 今日 token
  • 本次 token
  • 预算上限

评估指标建议​

  • TopK 命中率
  • 引用准确率
  • 用户满意度

扩展方向​

  • 多文档检索
  • 引用高亮
  • 监控报表

成本控制策略（实用）​

  • 限制 TopN
  • 限制 max_tokens
  • 历史摘要

可观测字段建议​

  • traceId
  • model
  • inputTokens/outputTokens
  • latency

失败兜底建议​

  • 模型超时 → 切换备用模型
  • 引用缺失 → 返回“证据不足”

实战用例​

  • 问题：年假怎么计算？
  • 证据：员工手册 P12
  • 输出：答案 + 引用

RAG 评估模板​

问题: 年假如何计算
证据: doc-001-0002
TopK命中: 是
引用准确: 是

UI 组件拆分建议​

  • CitationPanel
  • CostPanel
  • TraceIdBadge

组件示例（简化版）​

function TraceIdBadge({ id }) {
  return <span>traceId: {id}</span>;
}

监控指标建议​

  • 请求总数
  • 错误率
  • 平均响应时长

常见问题​

  • 引用为空 → 证据不足
  • 成本过高 → TopN 过大

扩展路线​

  • 分权限文档检索
  • 语义高亮
  • 引用点击跳转

评估清单（RAG）​

  1. TopK 命中率
  2. 引用准确率
  3. 拒答准确率
  4. 回答完整性
  5. 引用覆盖率
  6. 证据长度合理性
  7. 证据重复率
  8. 用户满意度
  9. 成本控制
  10. 平均响应时长
  11. TTFT
  12. 超时率
  13. 失败率
  14. 复现率
  15. 回归通过率

附录：产品化 Checklist​

  • 多模型切换
  • 成本面板
  • 监控告警
  • 日志脱敏
  • 版本回滚

案例流程（简版）​

  1. 用户提问“年假规则”
  2. 检索证据 TopK
  3. 拼 Prompt
  4. 返回答案 + 引用

监控告警规则​

  • 错误率 > 5% 报警
  • 平均耗时 > 3s 报警
  • 引用缺失率 > 10% 报警

附录：常见问题​

  • 为什么引用面板为空？
  • 为什么回答不稳定？
  • 为什么成本过高？

测试用例（示例）​

  • 年假规则 → 引用员工手册
  • 退款流程 → 引用FAQ

FAQ​

Q: 为什么引用面板为空？​

A: 证据不足或检索失败。

Q: 为什么成本过高？​

A: TopN 过大或输入过长。

端到端验收清单​

  • 引用面板可用
  • 成本面板可用
  • traceId 可见
  • 错误码可追踪

最小演示流程​

  1. 上传文档
  2. 输入问题
  3. 查看引用
  4. 查看成本

附录：字段定义​

  • traceId：链路追踪
  • model：模型名称
  • token_in：输入 token
  • token_out：输出 token

最小完成标记​

  • 引用可展示
  • 成本可查看

补充清单​

  • 引用编号一致
  • 证据可展开
  • 成本可追踪

最终检查​

  • RAG 正常
  • 引用正常

完整可运行代码（RAG Mock Demo）​

源码目录：docs/demos/rag-demo

cd docs/demos/rag-demo/server
npm i
npm run dev