Guide · 使用教程
Voyage AI RAG 教程：嵌入召回、重排与证据质量评估
用脱敏样本走通嵌入与重排，分别评估 Recall、MRR、权限、引用和完整检索成本。
作者：Li Xuan·更新于 2026年10月10日
这篇教程完成一个小型检索实验：用 Voyage 把获准访问的资料和问题转成向量，得到候选，再用 Rerank 3 排序，最后根据人工标注的证据评估效果。示例用虚构政策和内存中的精确余弦检索，便于看清每一步；正式知识库再把候选召回接到向量库或混合检索。
开始前准备
准备 Voyage API key、Python 环境和至少 50 个脱敏问题。Key 放在服务端环境变量 VOYAGE_API_KEY，不要写进代码、浏览器或截图。每个问题标注能支持答案的 chunk ID；“资料中没有答案”的问题另标记，用于检查拒答。先核对账号额度、组织预算与数据处理条款。
安装官方 Python 包：
bash
python -m pip install voyageai
下方示例执行时会发送获准访问的文本并产生 API 用量。代码展示接口组合，不代表已对你的账号或业务资料做过在线测量。
第一步：固定模型、维度和权限范围
初次实验使用 voyage-4-lite、1024 维和浮点向量；文档任务为 document，问题任务为 query。把这组配置与 chunk 版本保存，查询时检查一致。不能因为两个向量长度相同，就认定它们来自兼容的向量空间。
示例先从已验证的用户身份取租户，再过滤资料，之后才调用 API。正式系统还应检查文档级 ACL、源文件撤权与日志权限。提示词不是访问控制；重排完成后才删除未授权结果也无法收回已经传出去的资料。
第二步：嵌入召回，再进行重排
将下面代码保存为 retrieval_demo.py。环境变量由你在本地安全设置，不在脚本里粘贴 key。
python
math
voyageai
MODEL =
DIMENSION =
tenant =
documents = [
{: , : ,
: },
{: , : ,
: },
{: , : ,
: },
{: , : ,
: },
]
allowed = [d d documents d[] == tenant]
allowed:
RuntimeError()
client = voyageai.Client()
doc_vectors = client.embed(
[d[] d allowed],
model=MODEL, input_type=,
output_dimension=DIMENSION, truncation=,
).embeddings
query =
query_vector = client.embed(
[query], model=MODEL, input_type=,
output_dimension=DIMENSION, truncation=,
).embeddings[]
():
(a) != (b):
ValueError()
denominator = math.sqrt((x*x x a)) * math.sqrt(
(x*x x b)
)
(x*y x, y (a, b)) / denominator denominator
scored = (
(allowed, doc_vectors),
key= pair: cosine(query_vector, pair[]), reverse=,
)
candidates = [doc doc, _ scored[:]]
reranked = client.rerank(
query=query, documents=[d[] d candidates],
model=, top_k=(, (candidates)),
truncation=,
)
result reranked.results:
doc = candidates[result.index]
(doc[], result.relevance_score, doc[])
常见问题
- 为什么区分 document 和 query？
- Voyage 在检索任务中使用对应输入类型，为文档和查询提供适合其用途的向量化处理。
- 同样维度的向量一定兼容吗？
- 不一定。模型空间、输出维度、数据类型与索引版本都要匹配；迁移时使用独立索引和题库验收。
- 重排结果的 index 对应哪份资料？
- 它对应本次传给 rerank 的候选列表位置，应用必须保留候选到原 chunk/source 的映射。
- 什么情况下该先改召回？
- 正确证据未进入候选时，先排查解析、切块、权限过滤、关键词和嵌入；重排无法找回未传入的内容。
- 租户权限应该什么时候过滤？
- 在候选形成与外部 API 调用之前，根据已验证身份和文档 ACL 过滤，避免未获准文本被发送出去。
- 这份教程给出了实际性能结果吗？
- 没有。示例展示接口组合和评估方法，运行需自己的账号；业务效果应使用脱敏题库、实际用量与人工证据标注测量。