完成第一次知识检索
这条最短路径适合已有 AIS 租户、希望将知识检索接入自己系统的开发者。目标是确认服务地址、密钥权限、知识库编码和检索响应四件事。
若你负责为客户自动开户，请从 渠道接入流程 开始；若只接入已配置好的问答应用，请阅读 应用对话。
1. 准备接入资料
| 资料 | 获取方式 | 验收条件 |
|---|---|---|
| API 服务地址 | 由部署方提供 | 服务端可通过 HTTPS 访问 |
| 平台 API Key | 租户开放平台密钥管理 | 本示例具备 knowledge_container=READ、knowledge_search=READ |
| 可用知识库 | 由管理员创建并导入测试资料 | 密钥创建人具有访问权限；目标资料完成处理并可用于检索 |
| 检索模型 | 由租户管理员配置 | 向量检索与重排序所需模型可用 |
模块权限与知识库权限分别校验。某个接口认证通过，不代表所有知识库均可访问。
2. 确认知识库编码
在可信服务端设置变量，替换占位值：
export BASE_URL="https://ais.example.com"
export AIS_API_KEY="tk-REPLACE_WITH_YOUR_KEY"
curl --get "${BASE_URL}/openapi/paas/v1/knowledge/container/list" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--data-urlencode "pageNo=1" \
--data-urlencode "pageSize=10"
成功响应为分页结构。下面只展示本步骤需要的业务字段：
{
"code": 8200,
"message": "SUCCESS",
"pageNo": 1,
"pageSize": 10,
"total": 1,
"totalPage": 1,
"data": [{"id": 101, "code": "partner_kb_001", "name": "产品知识库"}]
}
确认 code=8200，保存目标记录的 data[].code；不要使用 data[].id 作为检索的 containerId。完整字段见 知识库管理。
3. 发起知识检索
curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/retrieval" \
--header "Authorization: Bearer ${AIS_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"q": "产品支持哪些部署方式？",
"containerId": ["partner_kb_001"],
"alpha": 0.7,
"top_k": 5,
"rerank": true,
"score_threshold": 0.5
}'
{
"code": 8200,
"message": "SUCCESS",
"data": {
"references": [{"containerId": "partner_kb_001", "dataSetId": "partner_file_001", "dataSetName": "产品白皮书.pdf"}],
"paragraphs": [{"dataSetId": "partner_file_001", "page": 1, "content": "支持按项目约定进行部署。"}]
}
}
| 观察字段 | 说明 | 接入动作 |
|---|---|---|
code | 普通接口业务状态 | 非 8200 时进入错误处理 |
data.references | 文件级引用来源数组 | 保存/展示来源名称及业务编码 |
data.paragraphs | 命中片段数组 | 读取 content，按 dataSetId 关联引用 |
data.paragraphs[].page | 来源页码，部分来源可空 | 有值时用于来源定位 |
检索返回内容，不生成答案；完整响应字段与参数选择见 知识检索。