LangChat Pro 提供开放的 API 接口，支持外部系统通过 RESTful API 调用知识库检索服务，实现无缝集成和二次开发。
- 语义搜索：基于向量相似度的智能检索
- 多知识库支持：可同时检索多个知识库
- 灵活配置：支持自定义检索参数
- 高可用性：支持负载均衡和容错机制
创建 API Key
API Key 是访问知识库检索服务的认证凭证：
API Key 配置
| 配置项 | 说明 | 建议 |
|---|
| 密钥名称 | 便于管理的标识名称 | 使用业务相关命名 |
| 有效期 | 密钥的有效时间范围 | 定期轮换，建议 90 天 |
| 权限范围 | 可访问的知识库范围 | 按需分配最小权限 |
| IP 限制 | 允许访问的 IP 地址 | 生产环境建议启用 |
API Key 具有访问知识库的完整权限，请妥善保管，避免泄露。建议定期轮换密钥。
API 接口文档
基础信息
| 项目 | 详情 |
|---|
| 接口地址 | http://your-domain.com/v1/rag/search |
| 请求方式 | POST |
| 内容类型 | application/json |
| 认证方式 | Bearer Token |
请求头配置
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
请求参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|
knowledgeIds | array | 是 | - | 知识库 ID 列表 |
text | string | 是 | - | 检索查询内容 |
maxResults | number | 否 | 10 | 返回结果数量上限 |
minSimilarity | number | 否 | 0.75 | 最小相似度阈值 |
响应参数
| 字段名 | 类型 | 说明 |
|---|
code | number | 响应状态码 |
message | string | 响应消息 |
data | array | 检索结果列表 |
检索结果对象
| 字段名 | 类型 | 说明 |
|---|
knowledgeId | string | 知识库唯一标识 |
docsName | string | 文档名称 |
docsId | string | 文档唯一标识 |
embeddingId | string | 向量嵌入标识 |
text | string | 匹配的文本内容 |
score | number | 相似度分数 (0-1) |
rerankedScore | number | 重排序后的分数 |
source | string | 数据来源类型 |
metadata | object | 元数据信息 |
调用示例
cURL 请求示例
curl --request POST \
--url "http://127.0.0.1:8100/v1/rag/search" \
--header "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx" \
--header "Content-Type: application/json" \
--data '{
"knowledgeIds": ["kb_8a7e38653e344047b417f365a66f4ca1"],
"text": "LangChat 平台功能介绍",
"maxResults": 5,
"minSimilarity": 0.7
}'
JavaScript 请求示例
const response = await fetch('http://127.0.0.1:8100/v1/rag/search', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
knowledgeIds: ['kb_8a7e38653e344047b417f365a66f4ca1'],
text: 'LangChat 平台功能介绍',
maxResults: 5,
minSimilarity: 0.7
})
});
const result = await response.json();
console.log(result);
Python 请求示例
import requests
url = "http://127.0.0.1:8100/v1/rag/search"
headers = {
"Authorization": "Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json"
}
data = {
"knowledgeIds": ["kb_8a7e38653e344047b417f365a66f4ca1"],
"text": "LangChat 平台功能介绍",
"maxResults": 5,
"minSimilarity": 0.7
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)
响应示例
成功响应
{
"code": 200,
"message": "success",
"data": [
{
"knowledgeId": "kb_8a7e38653e344047b417f365a66f4ca1",
"docsName": "LangChat.md",
"docsId": "7af40d3c6fe91691ce56718d439aaf7a",
"embeddingId": "emb_1234567890",
"text": "LangChat 是一个基于 RAG 技术的 AIGC 平台，提供智能对话和知识检索服务。",
"score": 0.8534821012722914,
"rerankedScore": 0.9234567890123456,
"source": "vector",
"metadata": {
"knowledgeId": "kb_8a7e38653e344047b417f365a66f4ca1",
"docsId": "7af40d3c6fe91691ce56718d439aaf7a",
"docsName": "LangChat.md",
"chunkIndex": 3,
"totalChunks": 15
}
}
]
}
错误响应
{
"code": 400,
"message": "Invalid knowledge ID or insufficient permissions",
"data": null
}
检索流程
性能优化建议
参数调优
| 场景 | maxResults | minSimilarity | 说明 |
|---|
| 精确检索 | 5-10 | 0.8-0.9 | 高精度，少噪声 |
| 广泛检索 | 10-20 | 0.6-0.7 | 平衡精度与覆盖 |
| 探索性检索 | 20-50 | 0.5-0.6 | 更多结果，容忍噪声 |
最佳实践
- 批量检索：对于多个知识库，建议使用批量接口
- 缓存策略：对频繁查询的结果进行缓存
- 错误处理：实现完善的错误处理和重试机制
- 监控告警：监控 API 调用量和响应时间
建议在生产环境中实施适当的限流和监控机制，确保服务稳定性。
