从 ingest 到 runtime,一份能做出来的后端方案

§ 01整体架构

1.1 高层视图

五层结构:浏览器侧的 widget,Vercel 上的 Next.js,Convex 一体化后端,Vercel AI SDK 抽象层,和外部 LLM/数据源。L3 LLM 抽象层是关键——它让我们随时切 Claude / OpenAI / ILMU 而不改业务代码,这是避免 provider lock 的命脉。所有跨端实时同步走 Convex reactive query——这是 ADR-019 的核心收益。

1.2 关键模块清单

1.3 SDK 体系 — Vercel AI SDK 抽象层(根据 LiuWei 评审强调)

LLM Provider 切换不是"换一行 import" 那么简单——Claude / OpenAI 的 API 协议、tool calling 格式、streaming 协议都不一样。如果直接调每家自己的 SDK,以后换 provider 要改几百处代码。Vercel AI SDK 这层的存在,就是把这种切换成本压到一行。

这 3 个 SDK 之间的关系图见 §1.1 主架构图(L3 LLM 抽象层)。两种典型用法:

用法 1 · 直接用 Vercel AI SDK 调 LLM(不用 agent 组件时,例如 L1/L2 judge):

// 简单的一次性 LLM 调用
import { generateText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";

const result = await generateText({
  model: anthropic("claude-haiku-4-5"),  // ← provider 切换点
  prompt: "判断下列消息是否越狱..."
});

用法 2 · 通过 @convex-dev/agent 跑完整 ReAct 循环(主对话):

// 包了 ReAct 循环 + 状态持久化 + streaming + tool dispatch
import { Agent } from "@convex-dev/agent";
import { anthropic } from "@ai-sdk/anthropic";
import { components } from "./_generated/api";

const supportAgent = new Agent(components.agent, {
  languageModel: anthropic("claude-sonnet-4-5"),  // ← 注意 key 是 languageModel
  instructions: SYSTEM_PROMPT,
  tools: { searchOrders, ragSearch },
  maxSteps: 5
});

await supportAgent.generateText(ctx, { threadId }, { prompt: userMessage });

两种用法共享同一个 provider 适配器(@ai-sdk/anthropic),所以 provider 切换在两个层面统一生效——这是 L3 抽象层的真正价值。

§ 02平台层

2.1 我同意 ADR-019,但理由稍微不同

ADR-019 文档强调 reactive query 解决"三端共享状态"。这点对。但我更看重以下两点:

1. @convex-dev/agent + @convex-dev/rag + @convex-dev/workpool 三个组件正好命中我们的核心需求。这相当于 1500–2000 行代码不用自己写——对 3 人团队 3 个月做 MVP 来说,这是决定性的杠杆。
2. 多租户隔离原生支持。Convex vectorIndex 支持 filterFields,允许在向量搜索时按 merchant_id 过滤,无需为每个商家建独立 namespace——这是 pgvector 需要额外工作才能做到的。

2.2 我对 Convex 的担忧(必须明示)

2.3 部署拓扑 — ADR-007 vs ADR-019 对比

Vercel 保留:Next.js 的 SSR + Edge runtime 对 widget 的 SEO 和加载速度都有用,jovie 的 UI 工作建立在 Next.js 上。Convex 不取代 Vercel——它取代的是 Fly + Neon + Upstash + R2。

Langfuse 单独自托管:Langfuse 自己就是个完整服务(自带 DB、自带 UI),不进 Convex。Fly.io 跑一个 docker,5 USD/月就够。

§ 03数据模型

3.1 ER 图

3.2 关键 Schema 决策

{
  document_id: Id<"documents">,
  start_char: number,    // 在 chunk 内的起始字符
  end_char: number,
  text_excerpt: string   // 冗余存,方便调试和审计
}

3.3 索引策略

// 1. 向量索引:RAG 检索的命脉
documents.vectorIndex("by_embedding", {
  vectorField: "embedding",
  dimensions: 1024,                  // 见 §4.3 Voyage 3 选型
  filterFields: ["merchant_id"]      // 多租户隔离
})

// 2. 全文索引:hybrid 检索的另一半
documents.searchIndex("by_text", {
  searchField: "text",
  filterFields: ["merchant_id"]
})

// 3. 按 merchant + 时间倒序:admin 看对话列表
conversations.index("by_merchant_time", ["merchant_id", "started_at"])

// 4. 按 conversation:加载消息
messages.index("by_conversation", ["conversation_id", "created_at"])

// 5. content_hash 去重:不重复爬同一 URL
documents.index("by_hash", ["merchant_id", "content_hash"])

§ 04RAG Ingest 流水线

4.0 数据获取的法律边界(根据 LiuWei 评审更新)

这一节是产品原则,定义了 §4.1 流水线的边界。没有这一节,后面所有技术细节都在错误地基上。

为什么这样设计?

1. 法律责任清晰。主动爬陌生网站属于"未授权访问"灰色地带——即使技术上能爬,出问题责任在我们。商家签约时勾选"我授权 CS-EverySystem 访问以下来源" = 法律授权明确,责任归商家。

2. robots.txt 不再是把关者。robots.txt 是给陌生爬虫的礼仪;对授权过的爬虫,商家自己就是规则,无需 robots 把关。所以 §4.1 流水线不再检查 robots.txt——既然商家给了我们 URL,他自己就负责合规性。

3. 内容质量更高。商家精选的 URL / 文档 / API 端点,比我们 BFS 爬出来的杂乱内容(包括过时页面、内部测试页、404)质量好得多。RAG 的 grounded_rate 直接受益。

4. 销售也要遵守这个原则。销售前的 demo 没签约 = 没授权。我们的方案是让客户签一份《Demo 数据使用授权书》(一页 PDF,5 分钟电子签名)——明确"为 demo 目的访问 URL X/Y/Z,demo 后数据销毁"。这跟生产阶段原则一致,避免双标。

商家授权的 4 种方式

商家在 /admin 看到 4 种数据来源,任选(也可组合):

这意味着 §4.1 的流水线不再是"线性 4 阶段",而是"4 个入口 → 共享后段"——上传文档跳过 Fetch + 部分 Extract,API 端点跳过更多。

4.1 整体流程

4.2 Chunking 策略

4.3 Embedding 模型选型 — Voyage 3

Voyage 3 胜出的理由:

• MTEB 多语言榜单 1024 维段位里中文 + 马来语 + 英语都靠前
• 维度只有 1024,Convex 存储 + 向量索引成本是 OpenAI large 的 1/3
• 价格比 Cohere 便宜 40%
• 关键:马来语在小维度模型里普遍表现差,Voyage 3 是少数过线的

4.4 Hybrid 检索 + Reranker

Query 改写(默认开):用户问"这鞋子能洗吗",直接拿去搜可能不准。先用 LLM(便宜的 Haiku 级)改写成"鞋子清洗方法 鞋子保养"。这步增加成本但提升 grounded_rate。

RRF 融合 (Reciprocal Rank Fusion):合并向量 + BM25 结果的标准算法,不需要调权重,鲁棒性好。

Voyage Rerank-2:跟 embedding 同一家。$0.05/M tokens,延迟 100–200ms,不是瓶颈。

4.5 Cited-span 实现

retrieve 之后给 LLM 的 prompt 长这样:

[相关文档片段]
<doc id="d_001" url="https://shoestore.com/returns">
我们提供 14 天无理由退货。客户需要在收到商品后 14 天内...
</doc>
<doc id="d_002" url="https://shoestore.com/faq">
退货流程:1. 联系客服 2. 邮寄商品...
</doc>

[规则]
1. 你必须基于上述文档回答。
2. 每条事实陈述必须用 <cite doc="d_001" start="0" end="15"/> 标注引用。
3. 如果文档不足以回答,直接说"我无法确定,请联系人工"。

LLM 输出:

我们支持 14 天无理由退货<cite doc="d_001" start="6" end="14"/>。
退货流程是:先联系客服,然后邮寄商品<cite doc="d_002" start="5" end="22"/>。

后处理把 <cite> 标签解析出来,存进 messages.cited_spans。L2 防御层验证回答里每个事实陈述至少有一个 cite,否则判 hallucination,要求重写。

§ 05Agent 编排层

5.1 ReAct 循环 — 用 @convex-dev/agent 封装

不自己手写 600 行,用 Convex 官方组件。但对组件的扩展点(中间件)我们要写自己的:

5.2 Tool 注册与 Custom Actions Runtime

每个商家在 tool_definitions 表里配置自己的工具:

{
  merchant_id: "shoestore",
  name: "search_orders",
  description: "根据邮箱查找订单",
  schema: {
    type: "object",
    properties: { email: { type: "string", format: "email" } },
    required: ["email"]
  },
  http_endpoint: "https://shoestore.com/api/orders/search",
  auth: { type: "bearer", secret_ref: "shoestore_orders_token" },
  requires_approval: false,
  timeout_ms: 10000
}

Agent 启动时,动态把这些定义注册成 Vercel AI SDK 的 tool。代码不需要为每个商家硬编码。

5.3 模型路由策略

不是所有请求都用 Claude Opus。三档分流:

为什么默认 Sonnet 不 Opus:Sonnet 4.5 的 tool use 准确率已经够高,Opus 贵 5x 但对客服场景边际收益不大。Premium plan 再升 Opus。

5.4 Streaming + Token Budget

• Streaming:用 Vercel AI SDK 的 streamText,token 边出边推到前端。p95 ≤ 3s 主要靠"首 token 时间"达成,不是"全部生成完毕"。
• Token budget:单对话累计 input+output > 30K token 强制 summarize 历史。防长对话失控的标准手段。

§ 06多层防御

6.2 L1 输入审查的 LLM-judge

用 Haiku 在一个 prompt 里同时回答三件事:

任务:判断下面的用户消息。

消息:"{user_message}"

请用 JSON 回答:
{
  "is_jailbreak":  true/false,
  "is_relevant":   true/false,
  "contains_pii":  true/false,
  "reason": "..."
}

6.3 L2 cited-span grounded 检查 (我的强主张)

6.4 PII Redactor

不自己造,用 Microsoft Presidio(开源,Apache 2.0)。预置了信用卡、电话、邮箱等检测器,马来西亚 IC 格式需要加自定义 recognizer。

部署架构:Convex 函数只允许 JS/TS,Presidio 是 Python——所以 Presidio 必须独立部署。推荐用官方 Docker 镜像跑在 Fly.io 上,Convex action 通过 HTTP 调用:

# 部署
docker run -d -p 5001:3000 mcr.microsoft.com/presidio-analyzer:latest
docker run -d -p 5002:3000 mcr.microsoft.com/presidio-anonymizer:latest

# Convex action 调用
const result = await fetch("https://presidio.cs-everysystem.fly.dev/analyze", {
  method: "POST",
  body: JSON.stringify({ text, language: "en" })
});

规模化考虑:Presidio Analyzer 单实例能扛 ~50 req/s。月 1-3 完全够用,后期需要考虑横向扩展或换成更轻量的 regex 方案处理热路径,LLM 触发的深度分析才走 Presidio。

替代方案:如果 Presidio HTTP 延迟成为瓶颈,可以用 LLM-judge(Haiku)在 L1/L2 直接做 PII 检测——不如 Presidio 准但延迟低 50%,且不用维护额外服务。这是值得跟 LiuWei 讨论的实现细节(见 §11)。

6.5 Cost Circuit Breaker

每次 LLM 调用后写入 audits.cost_usd,然后查 conversation 累计。三档阈值:

• 单对话:$0.50(约 50 万 token Sonnet,正常对话用不到 1/10)
• 单访客 / 小时:$2.00
• 单商家 / 天:$50.00(月 free tier)

超限处理:不直接 500,给一句"系统繁忙,稍后再试"的 fallback,后台标记。

§ 07可观测性 + Eval

7.1 双轨制观测

为什么双轨:Langfuse 擅长 LLM 调用链可视化,但它不知道我们的业务概念(merchant、approval flow、状态机)。Convex audits 表反过来。

7.2 OpenTelemetry 集成

Convex action 内每个 LLM 调用、每个 tool 调用、每次 RAG 检索都开一个 span:

const span = tracer.startSpan("rag.retrieve");
span.setAttributes({
  "merchant.id": merchantId,
  "rag.query":   query,
  "rag.top_k":   50
});
const docs = await retrieve(...);
span.setAttribute("rag.results.count", docs.length);
span.end();

trace 自动 export 到 Langfuse(via OTLP HTTP exporter)。

7.3 Eval 体系 (Promptfoo)

500 个 case 的来源:

每天自动跑:CI 跑全集,主分支跑 smoke set (~50 case)。

关键指标:task_success · grounded_rate · tool_use_accuracy · instruction_following_score · safety_score

§ 08Browser-use / CUA

8.1 定位

基于主文档"browser-use 是销售工具,生产用 <script>"的立场,我推断 browser-use 和 CUA 不进 hot path。理由:

• Browser-use 单步耗时 2–5s(LLM 决策 + 浏览器渲染),做客服回答太慢
• 不稳定(网页改版就坏)
• 贵(每个动作消耗 LLM token)
• 对生产工作,Custom Actions Runtime + 商家自配 API 更可靠

8.2 销售场景的具体用法

8.3 CUA 暂时不投入

月 1–3 不做 CUA。理由:真正需要 CUA 的客户极罕见(纯桌面系统的 SME 几乎不存在)、Anthropic Computer Use 还在快速迭代投资过早、把这个时间用来打磨 Site Scan + RAG 收益更大。如果月 4+ 真碰到桌面系统客户,再评估。

§ 09成本与性能预估

9.1 单次客户对话成本

假设一次对话 5 轮,每轮 2 次 LLM 调用(主回答 + L1/L2 judge):

9.2 性能目标分解 — p95 ≤ 3s

9.3 单商家月成本估算

假设中等商家:每月 1000 对话(基于 §9.1 单对话 ~$0.12)

§ 10里程碑映射 + 风险清单

10.1 这份方案对应里程碑的覆盖

10.2 风险清单

§ 11Open Questions

1. 《Demo 数据使用授权书》模板谁来出?需要一份能给销售团队即用的 PDF 模板(法律边界 + 销售友好措辞),建议找律师朋友审一稿。这份在 §4.0 + §8.2 都引用了,是销售合规的关键(根据 LiuWei 评审新加)。
2. PII Redactor 部署位置:Presidio 单独 Fly.io 容器,还是直接在 L1/L2 用 Haiku LLM-judge 替代?(取舍:准确度 vs 延迟,见 §6.4)
3. @convex-dev/agent 实测有多灵活?我们的 L1/L2/Tool guard 中间件能不能干净地注入?如果不能,要不要回到自写 600 行 ReAct?
4. 模型 provider 默认是 Claude 还是要双跑 Claude+GPT 投票?(影响成本和 grounded_rate)
5. ILMU(本地模型)什么时候接入?月 1 还是月 3 后?有马来政府客户的潜在 lead 在催吗?
6. Eval 跑在哪里?Promptfoo CLI 跑 GitHub Actions 还是单独 worker?跟 Convex 怎么集成?
7. Resolution detection 的 schema 我留了占位,但具体 detection 逻辑你之前提过没?月 3 再设计?
8. Langfuse 自托管 vs Cloud:自托管真省钱但要管;Cloud 头几个月免费够用。先 Cloud 后迁移?
9. Widget 注入的安全模型:第三方 cookie / iframe / postMessage,需要单独一份 design doc。这部分跟 jovie 也要对齐。
10. 5 层防御是否合适?(根据 LiuWei 评审新加)需要 trade-off 量化:每层增加多少延迟/成本 vs 防住多少类型攻击?是否可以合并某些层?这要月 1 实测后回答。

§ 12总结

核心判断

• Convex 是对的(理由 §2.1)
• @convex-dev/agent + rag + workpool 三个组件能省 1500+ 行代码——这是 3 人团队 3 个月做 MVP 的关键杠杆
• RAG 数据获取走"商家授权"路线(§4.0,根据 LiuWei 评审):4 入口(URL / Sitemap / 文档 / API)、不主动爬、不查 robots.txt——签约即授权
• RAG 用 hybrid + Voyage 3 + Voyage Rerank-2 + 严格 cited-span,是 grounded_rate ≥ 90% 的最现实路径
• Browser-use / CUA 严格控制在销售阶段 + 需要 demo 授权书,生产路径只走 Custom Actions Runtime
• 多层防御不能只靠"模型自己学好"——cited-span 必须强制验证

请 LiuWei 拿你的版本对照,我们重点讨论 §11 的 10 个 open questions(其中 #1 demo 授权书模板和 #10 防御层 trade-off 是这次评审新加的),然后敲定最终方案。