项目三 Workers AI 与 Vectorize 知识助手

用双语 embeddings、可追溯 metadata、受保护索引入口和无上下文分支完成最小 RAG。

PROJECT 03进阶约 70 分钟产出：带来源的最小 RAG

完成标准

/index 与 /ask 分别需要 Secret，Vectorize metadata 可追溯原文；查询只传 embedding.data[0]，空命中返回 404 no_context，不让模型无依据回答。

Workers AI 与 Vectorize 知识助手架构图 — 写入路径生成向量并异步 upsert；查询路径先检索 metadata，再把受限上下文交给生成模型。查看原图

01
索引
Secret 保护的文档写入入口。
02
向量化
bge-m3 生成中英文 embeddings。
03
检索
Vectorize 返回原文与来源 metadata。
04
回答
只有命中上下文才调用生成模型。

文件与资源

README.md

wrangler.jsonc

index.mjs

源码位于 examples/ai-knowledge-assistant/。INGEST_KEY 与 QUERY_KEY 都是 Secret，不能进入 vars。

准备与验证

创建双语向量索引

pnpm wrangler vectorize create orange-book-knowledge --preset @cf/baai/bge-m3

该命令创建远程资源，会消耗账号权限；执行前确认目标账号。--preset 让 Wrangler 根据当前 embeddings 模型配置维度与 metric。

设置 Secret 并启动

cp examples/ai-knowledge-assistant/.dev.vars.example examples/ai-knowledge-assistant/.dev.vars
pnpm wrangler dev --config examples/ai-knowledge-assistant/wrangler.jsonc

替换 .dev.vars 中两个占位值并且不要提交该文件。Workers AI 与 Vectorize 会使用远程服务额度，不属于完全离线预览；生产 Secret 需在确认目标账号后另行设置。

索引一条内容

curl -i http://127.0.0.1:8787/index \
  -H 'content-type: application/json' \
  -H 'x-ingest-key: <your-local-secret>' \
  --data '{"documents":[{"id":"tls-strict","text":"新站优先使用 Full strict。","source":"/zh/docs/fundamentals/tls-modes"}]}'

返回 202 indexing 后等待几秒再查询，因为 Vectorize upsert 异步可见。

提问并检查来源

curl -i http://127.0.0.1:8787/ask \
  -H 'content-type: application/json' \
  -H 'x-query-key: <your-local-query-secret>' \
  --data '{"question":"新站应该选择什么 TLS 模式？"}'

检查 sources 来自已索引 metadata；删除索引内容后应走 no_context，而不是编造答案。

回滚与安全边界

首先撤销公开路由或回滚 Worker 版本；索引数据单独备份/重建。
轮换泄露的 INGEST_KEY 或 QUERY_KEY；仅删除代码无效。
QUERY_KEY 只是服务端教学保护，不能嵌入浏览器；公开 UI 还需要用户认证、滥用防护和成本限制。
模型名是时效配置，发布前检查模型目录、定价和数据处理政策。
检索内容按不可信参考数据进入 Prompt；本例只生成文本，不执行模型或文档提出的动作。