Vectara 使用教程：从创建语料到 API 检索的完整流程
Vectara 是一个托管式检索增强生成平台，你不需要自己维护向量数据库和嵌入模型，只要创建语料库、上传文档，再调用查询接口就能拿到带摘要的检索结果。
适合想快速验证 RAG 流程、又不想从零搭索引的开发者。
下面按实际使用顺序讲清每一步。
开始前要准备什么
使用 Vectara 前需要有一封可接收验证邮件的邮箱，并在其控制台完成注册。
免费额度足够做功能验证，但具体配额和计费规则可能调整，以注册后控制台显示为准。
你需要拿到两样东西：一个是 API Key，在控制台的 API 访问页面生成；
另一个是 Corpus ID，创建语料库后获得。
API Key 分为不同权限，查询和写入建议使用不同密钥，避免把高权限密钥写进前端代码。
本地调试建议安装 curl，或者用 Python 的 requests 库。
下面示例统一用 curl，方便直接复制执行。
请把示例中的 YOUR_API_KEY 和 YOUR_CORPUS_ID 替换成实际值。
创建语料库并上传文档
登录 Vectara 控制台后，进入 Corpus 页面新建一个语料库。
创建时重点看两个配置：嵌入模型和分块策略。
嵌入模型决定语义匹配效果，分块策略影响长文档的检索粒度。
如果文档以短段落为主，可以保留默认分块；
如果是长报告，建议按标题或固定长度切分，避免单块过大导致检索精度下降。
创建完成后记下 Corpus ID。
接着上传文档，控制台支持直接上传文件，也可以用 API 写入。
以 API 写入一段文本为例：
curl -X POST "https://api.vectara.io/v1/index" \
-H "x-api-key: YOUR_API_KEY" \
-H "customer-id: YOUR_CUSTOMER_ID" \
-H "Content-Type: application/json" \
-d '{
"corpus_id": YOUR_CORPUS_ID,
"document": {
"document_id": "doc-001",
"title": "示例文档",
"metadata_json": "{\"source\":\"manual\"}",
"section": [{
"text": "这里放你要检索的正文内容。"
}]
}
}'注意 customer-id 也在控制台账户信息里能找到，缺少它会返回鉴权错误。
上传成功后，控制台文档列表会出现对应记录，状态变为已索引即可查询。
调用查询接口拿检索结果
查询接口是 Vectara 使用教程里最常调试的部分。
下面请求会返回与问题最相关的文档片段，并附带摘要：
curl -X POST "https://api.vectara.io/v1/query" \
-H "x-api-key: YOUR_API_KEY" \
-H "customer-id: YOUR_CUSTOMER_ID" \
-H "Content-Type: application/json" \
-d '{
"query": "如何配置检索参数？",
"search": {
"corpora": [{"corpus_id": YOUR_CORPUS_ID}],
"limit": 5
},
"summary": {
"response_lang": "zh",
"max_results": 3
}
}'返回结果里重点看 responseSet 数组，每一项包含 text、score 和文档元数据。score 越高表示语义越接近。
如果开了 summary，还会返回一段生成式摘要，适合直接展示给用户。
容易踩坑的几个地方
密钥权限混用：查询密钥只能调查询接口，写入密钥才能上传文档。
用错会返回 403，先检查密钥类型。
分块过大：单块文本太长时，检索结果容易“沾边但不精准”。
上传前按段落或标题切分，效果通常更稳定。
语料库未就绪：刚上传文档后立即查询可能返回空结果。
控制台显示索引完成后重试，或等待几十秒再查。
客户 ID 写错：customer-id 和 API Key 不匹配时，接口会报鉴权失败，复制时注意不要带多余空格。
怎么验证接入成功
先用控制台自带的查询框搜一个文档里明确存在的词，能返回对应片段说明索引正常。
再用 curl 调一次查询接口，确认返回 HTTP 200 且 responseSet 非空。
如果要做业务接入，建议把查询封装成后端接口，前端只传问题，不暴露 API Key。
常见疑问：Vectara 需要自己部署向量数据库吗？
不需要，索引和嵌入由平台托管。
免费额度够测试吗？
做小规模验证通常够用，正式流量前请以控制台配额为准。
整体流程就是创建语料库、上传文档、调用查询三步。
先跑通最小请求，再根据结果调整分块和返回条数，比一开始就追求复杂配置更稳妥。
