按智能体检索知识库
接口介绍
接口路径:POST /api/V1/open-portal/app/retriever/search/agent_kb
按智能体检索知识库内容:传入智能体 Code 和检索关键词,从指定智能体关联的知识库中查询相关文档片段或问答内容,并返回匹配结果列表。
- 支持通过
kb_names指定知识库名称列表以限定检索范围。 - 支持控制返回结果数量、是否重排、是否优先检索 QA,以及结果分数阈值。
- 返回结果包含文档 ID、文件名、问题、答案、正文内容、内容类型、匹配分数及相关元数据。
- 操作者用户 ID 由平台网关注入
X-App-User-Id,调用方不要自行设置。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| agent_code | string | 是 | 智能体 Code |
| query | string | 是 | 检索内容 |
| kb_names | array of string | 否 | 知识库名称列表,限定检索范围,默认 [] |
| top_k | integer | 否 | 返回 Top K 个结果,默认 10 |
| rerank | boolean | 否 | 是否重排结果,默认 true |
| check_qa_first | boolean | 否 | 是否优先检索 QA,默认 true |
| score_threshold | number | 否 | 结果分数阈值,默认 0 |
调用示例
接口采用 AK/SK 签名鉴权,请求头需携带 X-App-Id、X-App-Key、X-Timestamp、X-Nonce、X-Signature。签名 = HMAC-SHA256(AppSecret, METHOD\nPATH\nTIMESTAMP\nNONCE),只使用 URL path,不含 query。
下方命令可直接复制运行:替换凭证后先跑一次即可验证连通性(在线调试),再按「请求参数」修改 -d 内容调试其它入参。
bash
APP_ID="app_xxxxxxxx"
APP_KEY="ak_xxxxxxxx"
APP_SECRET="sk_xxxxxxxx"
BASE_URL="https://open.agibot.com"
API_PATH="/api/V1/open-portal/app/retriever/search/agent_kb"
TS_MS=$(( $(date +%s) * 1000 ))
NONCE="$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n')"
SIGNATURE=$(printf 'POST\n%s\n%s\n%s' "$API_PATH" "$TS_MS" "$NONCE" \
| openssl dgst -sha256 -hmac "$APP_SECRET" | sed 's/^.* //')
curl -sS -X POST "$BASE_URL$API_PATH" \
-H "Content-Type: application/json" \
-H "X-App-Id: $APP_ID" \
-H "X-App-Key: $APP_KEY" \
-H "X-Timestamp: $TS_MS" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE" \
-d '{
"agent_code": "AI_AGENT_28159402",
"query": "远征",
"kb_names": ["产品手册"],
"top_k": 10,
"rerank": true,
"check_qa_first": true,
"score_threshold": 0
}'
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 状态码,成功为 0 |
| success | boolean | 请求是否成功 |
| message | string | 错误提示;成功时为空 |
| data | array | 匹配结果列表 |
| data.id | string | 结果 ID |
| data.doc_id | string | 文档 ID |
| data.filename | string | 文档名称 |
| data.content | string | chunk 内容 |
| data.question | string | 问题(QA 内容时返回) |
| data.answer | string | 答案(QA 内容时返回) |
| data.content_type | string | chunk 类型 |
| data.score | number | 结果分数 |
| data.metadata | object | 结果元信息 |
返回示例
json
{
"code": 0,
"success": true,
"message": "",
"data": [
{
"id": "chunk-1",
"doc_id": "doc-1",
"filename": "产品手册.pdf",
"content": "远征机器人支持……",
"question": null,
"answer": null,
"content_type": "document",
"score": 0.92,
"metadata": {}
}
]
}
常见错误
- 缺少
agent_code或query。 - 智能体不存在或不属于当前租户。
- 智能体未关联任何知识库。
- 鉴权签名错误或过期。