所有管理/查询接口使用 Bearer Token 认证,在请求头中传入:
Authorization: Bearer <API_KEY>
| 认证方案 | 环境变量 | 适用端点 |
|---|---|---|
| Dify Auth | DIFY_API_KEY |
/dify/retrieval |
| Internal Auth | INTERNAL_API_KEY |
/collections/*, /vectors/* |
| Server Auth | SERVER_API_KEY |
/search/* |
| MCP Auth | MCP_API_KEY |
/mcp |
鉴权为 fail-closed:任一 Key 未配置时服务拒绝启动;运行期探测到 Key 缺失则返回 HTTP 503(而非放行)。凭证错误返回 HTTP 401。 例外:
/dify/retrieval遵循 Dify 协议,错误一律返回 HTTP 200 + body 中的error_code(1002)。
所有管理/搜索接口使用统一响应格式:
{
"success": true,
"data": { ... },
"error": null
}
错误时:
{
"success": false,
"data": null,
"error": {
"code": "COLLECTION_NOT_FOUND",
"message": "集合 my_collection 不存在"
}
}
注意:认证失败返回标准 HTTP 错误格式(
{"detail": "..."}),不遵循本统一格式。详情见 认证 章节。Dify 接口使用独立响应格式,见 Dify 检索。
| Code | HTTP | 说明 |
|---|---|---|
COLLECTION_NOT_FOUND |
400 | 集合不存在 |
COLLECTION_ALREADY_EXISTS |
400 | 集合已存在 |
INVALID_COLLECTION_NAME |
400 | 集合名称不合法 |
INVALID_VECTOR_SIZE |
400 | 向量维度不匹配 |
INVALID_VECTOR_DATA |
400 | 向量数据格式错误 |
POINT_NOT_FOUND |
400 | 数据点不存在 |
INVALID_QUERY_VECTOR |
400 | 查询向量无效 |
INVALID_FILTER |
400 | 过滤条件无效 |
QDRANT_CONNECTION_ERROR |
400 | Qdrant 连接失败 |
INTERNAL_ERROR |
500 | 内部错误 |
/vectors/query、/vectors/scroll、/vectors/payload、/search、/search/hybrid 支持 payload 过滤:
{
"filter": {
"must": [
{ "key": "category", "match": { "value": "tech" } },
{ "key": "content", "match": { "text": "机器学习" } }
],
"must_not": [
{ "key": "deleted", "match": { "value": true } }
],
"should": [
{ "key": "tag", "match": { "value": "featured" } }
]
}
}
| 条件组合 | 说明 |
|---|---|
must |
所有条件必须满足(AND) |
must_not |
所有条件必须不满足 |
should |
至少一个条件满足(OR) |
| Match 类型 | 说明 |
|---|---|
value |
精确匹配,类型 str/int/bool |
text |
文本包含匹配(MatchText) |
range |
范围匹配,字段 gte(>=)、lte(<=) |
curl -X GET http://localhost:8844/collections \
-H "Authorization: Bearer $INTERNAL_API_KEY"
响应:
{
"success": true,
"data": ["my_collection", "kb_docs"],
"error": null
}
curl -X GET http://localhost:8844/collections/my_collection \
-H "Authorization: Bearer $INTERNAL_API_KEY"
响应:
{
"success": true,
"data": {
"name": "my_collection",
"vector_size": 1024,
"distance": "Cosine",
"points_count": 5000,
"status": "green",
"optimizer_status": "ok",
"segments_count": 2,
"indexed_vectors_count": 5000,
"sparse_vector": true,
"vectors": {
"dense": {"size": 1024, "distance": "Cosine"}
},
"metadata": {"description": "技术文档知识库"}
},
"error": null
}
| 字段 | 类型 | 说明 |
|---|---|---|
vector_size |
int | 默认向量维度(兼容字段,多向量集合为第一个向量) |
distance |
string | 默认距离度量(兼容字段) |
status |
string | 集合状态 green / yellow / red |
optimizer_status |
string/dict/null | 优化器状态,"ok" 或 {"error": "..."};集合为 red 时这里是失败原因 |
segments_count |
int/null | 段数量 |
indexed_vectors_count |
int/null | 已建索引的向量数 |
sparse_vector |
bool | 是否启用稀疏向量索引(BM25) |
vectors |
dict | 所有向量配置 {name: {size, distance}},单向量集合也有 {"": ...} 默认键 |
metadata |
dict/null | 集合元数据(创建时设置的描述/说明) |
单向量(等价于传统的 vector_size + distance):
curl -X POST http://localhost:8844/collections \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"collection_name": "my_collection", "vectors": {"dense": {"size": 1024, "distance": "Cosine"}}}'
多向量(独立搜索不同语义维度,如产品名/描述/图片):
curl -X POST http://localhost:8844/collections \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"collection_name": "products", "sparse_vector": false, "vectors": {"product_name": {"size": 1024, "distance": "Cosine"}, "image_full": {"size": 1024, "distance": "Cosine"}}}'
请求体:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
collection_name |
string | 是 | - | 集合名称 |
vectors |
dict[str, object] | 是 | - | 向量配置 {name: {size: int, distance: "Cosine"\|"Euclidean"\|"Dot"}},至少一个 |
sparse_vector |
bool | 否 | true |
是否启用稀疏向量(BM25)。默认名 "dense" → "sparse",其他名 → {name}_sparse |
type |
string | 否 | "document" |
集合类型:"document"(文档库)/ "qa"(问答库),自动存入 metadata |
metadata |
dict | 否 | null | 集合元数据(描述/说明)。创建时 type 字段会自动合并到 metadata 中 |
响应:
{
"success": true,
"data": { "collection_name": "my_collection", "operation": "created" },
"error": null
}
curl -X DELETE http://localhost:8844/collections/my_collection \
-H "Authorization: Bearer $INTERNAL_API_KEY"
响应:
{
"success": true,
"data": { "collection_name": "my_collection", "operation": "deleted" },
"error": null
}
curl -X PATCH http://localhost:8844/collections/my_collection \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sparse_vector": true}'
请求体:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
sparse_vector |
bool | 否 | null | true 启用 / false 禁用稀疏向量,null 不做修改 |
metadata |
dict | 否 | null | 集合元数据(描述/说明),null 不做修改 |
响应:
{
"success": true,
"data": { "collection_name": "my_collection", "operation": "updated" },
"error": null
}
为 payload 字段创建索引以加速过滤查询:
curl -X PUT http://localhost:8844/collections/my_collection/index \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"field_name": "category", "field_schema": "keyword"}'
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
field_name |
string | 是 | payload 字段名 |
field_schema |
string | 是 | 索引类型: keyword/integer/float/geo/text/bool/datetime/uuid |
keyword适合 category/tag 等值匹配;integer/float适合数值范围;text适合全文搜索。
响应:
{
"success": true,
"data": {
"collection_name": "my_collection",
"operation": "index_created",
"field_name": "category",
"field_schema": "keyword"
},
"error": null
}
curl -X DELETE http://localhost:8844/collections/my_collection/index/category \
-H "Authorization: Bearer $INTERNAL_API_KEY"
响应:
{
"success": true,
"data": {
"collection_name": "my_collection",
"operation": "index_deleted",
"field_name": "category",
"field_schema": null
},
"error": null
}
写入预先计算好的稠密向量,可选附带稀疏向量。单次最多 1000 条:
curl -X POST http://localhost:8844/vectors/upsert \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "my_collection",
"points": [
{"id": "doc1", "vector": [0.1, 0.2, ...], "payload": {"title": "Doc 1"}, "sparse_vector": {"indices": [10, 20], "values": [2.0, 1.0]}},
{"id": "doc2", "vector": {"product": [0.1, ...], "image": [0.3, ...]}, "payload": {"title": "Doc 2"}}
]
}'
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
collection_name |
string | 是 | 目标集合 |
points |
list | 是 | 数据点数组,最多 1000 条 |
Point 结构:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
id |
string/int | 是 | - | 唯一标识 |
vector |
list[float] | dict[str, list[float]] | 是 | - | 单向量 [0.1, ...] 或命名向量 {"product": [...], "image": [...]} |
payload |
dict | 否 | null | 附加元数据 |
sparse_vector |
object | 否 | null | 单路 {indices, values} 或多路 {dense_name: {indices, values}, ...},不传则不写入 |
vector支持list[float](匿名)或dict[str, list[float]](命名)。sparse_vector同理,格式跟随vector:匿名集合传单路,命名集合可按稠密名传多路。使用/vectors/upsert-text时稀疏向量自动生成。
响应:
{
"success": true,
"data": {
"collection_name": "my_collection",
"inserted_count": 2,
"failed_count": 0,
"errors": [],
"elapsed_ms": null,
"cache_stats": null
},
"error": null
}
传入原始文本,服务端自动生成稠密向量(Embedding API)和稀疏向量(BM25 分词),单次最多 100 条。支持两种模式:
单向量模式 (text)——生成一个稠密向量(named "dense")+ 稀疏向量:
curl -X POST http://localhost:8844/vectors/upsert-text \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "my_collection",
"points": [
{"id": "doc1", "text": "Python 是一门强大的编程语言...", "payload": {"title": "Doc 1"}}
]
}'
多向量模式 (texts)——每个 key 独立生成稠密向量 + 同名稀疏向量("dense" → "sparse",其他 → {name}_sparse):
curl -X POST http://localhost:8844/vectors/upsert-text \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "products",
"points": [
{"id": "p1", "texts": {"product_detail": "产品名称: 乳清蛋白...", "image_full": "白色罐装...", "image_visual": "白色 圆柱形..."}, "payload": {"品牌": "健乐多"}}
]
}'
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
collection_name |
string | 是 | 目标集合 |
points |
list | 是 | 文本点数组,最多 100 条 |
TextPoint 结构:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
id |
string/int | 是 | - | 唯一标识 |
text |
string | 二选一 | - | 单向量模式,生成 "dense" 稠密向量 + 稀疏向量 |
texts |
dict[str,str] | 二选一 | - | 多向量模式,每个 key 独立生成稠密向量 + 同名稀疏向量 |
payload |
dict | 否 | null | 附加元数据 |
text和texts必须提供其一。Embedding API 调用受EMBEDDING_CONCURRENCY(并发数,默认 2)、EMBEDDING_MAX_RPM(每分钟请求数,默认 1800)和EMBEDDING_MAX_TPM(每分钟 token 数,默认不限)控制。QA 集合校验:如果集合创建时设置了
"type": "qa",写入时自动校验每个点的 payload 必须包含answer字段(question可选),缺失时将返回INVALID_VECTOR_DATA错误。
响应:
{
"success": true,
"data": {
"collection_name": "my_collection",
"inserted_count": 2,
"failed_count": 0,
"errors": [],
"elapsed_ms": 1250.5,
"cache_stats": {
"l1_hits": 1,
"l2_hits": 0,
"l3_calls": 1
}
},
"error": null
}
| 字段 | 类型 | 说明 |
|---|---|---|
failed_count |
int | 写入失败的点数 |
errors |
list[dict] | 失败的详情列表 |
elapsed_ms |
float | 请求耗时(毫秒) |
cache_stats |
dict | 嵌入缓存命中统计(l1_hits/l2_hits/l3_calls) |
curl -X POST http://localhost:8844/vectors/delete \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"collection_name": "my_collection", "ids": ["doc1", "doc2"]}'
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
collection_name |
string | 是 | 目标集合 |
ids |
list[string/int] | 是 | 要删除的 ID |
响应:
{
"success": true,
"data": { "collection_name": "my_collection", "deleted_count": 2 },
"error": null
}
curl -X POST http://localhost:8844/vectors/retrieve \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "my_collection",
"ids": ["doc1", "doc2"],
"with_payload": true,
"with_vectors": false
}'
请求体:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
collection_name |
string | 是 | - | 目标集合 |
ids |
list | 是 | - | ID 列表 |
with_payload |
bool | 否 | true | 返回 payload |
with_vectors |
bool | 否 | false | 返回向量 |
响应:
{
"success": true,
"data": {
"collection_name": "my_collection",
"points": [
{"id": "doc1", "payload": {"title": "Doc 1"}, "vector": null}
]
},
"error": null
}
curl -X POST http://localhost:8844/vectors/scroll \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "my_collection",
"limit": 20,
"offset": null,
"filter": {"must": [{"key": "status", "match": {"value": "active"}}]},
"with_payload": true,
"with_vectors": false
}'
请求体:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
collection_name |
string | 是 | - | 目标集合 |
limit |
int | 否 | 10 | 每页数量 |
offset |
string/int/null | 否 | null | 分页游标 |
filter |
FilterModel | 否 | null | 过滤条件 |
with_payload |
bool | 否 | true | 返回 payload |
with_vectors |
bool | 否 | false | 返回向量 |
响应:
{
"success": true,
"data": {
"collection_name": "my_collection",
"points": [
{"id": "doc5", "payload": {"status": "active"}, "vector": null}
],
"next_offset": "doc25"
},
"error": null
}
next_offset为null表示已到最后一页。
curl -X GET http://localhost:8844/vectors/count/my_collection \
-H "Authorization: Bearer $INTERNAL_API_KEY"
响应:
{
"success": true,
"data": { "collection_name": "my_collection", "count": 5000 },
"error": null
}
curl -X POST http://localhost:8844/vectors/query \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "my_collection",
"query_vector": [0.1, 0.2, 0.3, ...],
"limit": 5,
"filter": null,
"with_vectors": false,
"score_threshold": 0.5
}'
请求体:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
collection_name |
string | 是 | - | 目标集合 |
query_vector |
list[float] | 是 | - | 查询向量 |
limit |
int | 否 | 10 | 返回结果数 |
filter |
FilterModel | 否 | null | 过滤条件 |
with_vectors |
bool | 否 | false | 返回向量 |
score_threshold |
float | 否 | null | 分数阈值(0.0-1.0) |
dense_using |
string | 否 | null | 稠密向量名,默认为 dense,不存在时取第一个向量名 |
响应:
{
"success": true,
"data": {
"collection_name": "my_collection",
"results": [
{"id": "doc1", "score": 0.95, "payload": {"title": "Doc 1"}, "vector": null}
],
"total": 1
},
"error": null
}
为点设置 payload(合并模式,不覆盖未指定字段)。支持按 ID 列表或 filter 条件批量设置:
# 按 ID 列表
curl -X PUT http://localhost:8844/vectors/payload \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "my_collection",
"payload": {"category": "tech", "priority": 1},
"ids": [1, 2, 3]
}'
# 按 filter 条件
curl -X PUT http://localhost:8844/vectors/payload \
-H "Authorization: Bearer $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "my_collection",
"payload": {"status": "archived"},
"filter": {
"must": [{"key": "category", "match": {"value": "old"}}]
}
}'
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
collection_name |
string | 是 | 目标集合 |
payload |
dict | 是 | 要设置的 payload |
ids |
list[int|str] | 否 | 点 ID 列表(与 filter 二选一) |
filter |
FilterModel | 否 | 过滤条件(与 ids 二选一) |
ids和filter必须提供一个,否则返回 422。
响应:
{
"success": true,
"data": { "collection_name": "my_collection", "operation": "payload_set" },
"error": null
}
输入文本由服务端自动 Embedding 后检索:
curl -X POST http://localhost:8844/search \
-H "Authorization: Bearer $SERVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "my_collection",
"query_text": "如何使用 FastAPI 构建 REST API",
"limit": 5,
"filter": null,
"score_threshold": 0.5
}'
请求体:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
collection_name |
string | 是 | - | 目标集合 |
query_text |
string | 是 | - | 自然语言查询 |
limit |
int | 否 | 10 | 返回结果数 |
filter |
FilterModel | 否 | null | 过滤条件 |
score_threshold |
float | 否 | null | 分数阈值(0.0-1.0) |
dense_using |
string | 否 | null | 稠密向量名,默认为 dense,不存在时取第一个向量名 |
enable_rerank |
bool | 否 | true | 检索后是否用 reranker 重排。检索阶段按 round(limit×1.25) 过采样候选、重排后裁剪回 limit 条;重排后分数为 relevance_score,score_threshold 对其生效。未配置 reranker 时自动降级为不重排;reranker 调用失败时回退原始排序(前 limit 条,score_threshold 按原始分数过滤) |
响应:
{
"success": true,
"data": {
"results": [
{"id": "doc1", "score": 0.92, "payload": {"title": "FastAPI Guide"}, "vector": null}
],
"total": 1
},
"error": null
}
curl -X POST http://localhost:8844/search/hybrid \
-H "Authorization: Bearer $SERVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "my_collection",
"query_text": "Python 机器学习",
"limit": 10,
"filter": null,
"score_threshold": 0.5
}'
请求体:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
collection_name |
string | 是 | - | 集合名称 |
query_text |
string | 是 | - | 自然语言查询 |
limit |
integer | 否 | 10 | 返回结果数 |
filter |
object/null | 否 | null | payload 过滤条件 |
score_threshold |
float | 否 | null | 分数阈值,基于融合后的分数过滤(语义随 fusion_method 而异,见下) |
dense_using |
string | 否 | null | 稠密向量名,默认为 dense,不存在时取第一个向量名 |
sparse_using |
string | 否 | null | 稀疏向量名,不传自动推导("dense"→"sparse",其他→{name}_sparse) |
fusion_method |
string | 否 | rrf | 融合算法:rrf(排名融合)或 dbsf(分布分数融合) |
rrf_k |
integer | 否 | 2 | RRF 排序常数 k(与 Qdrant 官方默认一致);越小头部优势越明显。仅 fusion_method=rrf 时生效 |
rrf_weights |
list[float] | 否 | [2.0, 1.0] | RRF 两路权重 [dense, sparse],默认稠密加倍以抑制关键词堆砌型查询中稀疏路的虚高。仅 fusion_method=rrf 时生效 |
enable_rerank |
bool | 否 | true | 检索后是否用 reranker 重排。检索阶段按 round(limit×1.25) 过采样候选、重排后裁剪回 limit 条;重排后分数为 relevance_score,score_threshold 对其生效。未配置 reranker 时自动降级为不重排;reranker 调用失败时回退原始排序(前 limit 条,score_threshold 按原始分数过滤) |
混合搜索融合 Dense + Sparse BM25 两路结果,集合默认启用稀疏向量索引;稀疏向量不匹配或为空时自动降级为纯语义搜索。多向量集合请传入
dense_using指定稠密向量名,sparse_using默认自动推导,不传即可。两种融合算法的分数语义不同(均已归一化到 0-1): -
rrf:仅使用两路排名(忽略绝对分数),默认权重 [2,1] 稠密加倍——双路 rank 1 ≈ 1.0,稠密单路第一 ≈ 0.67,稀疏单路第一 ≈ 0.33;双路上榜时分数取决于两路名次。分布偏集中,适合无需按分数过滤、只要排序的场景。 -dbsf:各路分数按分布归一化后等权求和,再按本次结果集 min-max 归一化到 0-1(top1 = 1.0)。保留相关性幅度、区分度高,阈值语义为「相当于本次最佳结果的比例」,建议 0.4~0.6 起过滤弱相关。
使用 LLM Agent 进行查询理解、多步推理和工具调用,支持跨集合搜索:
curl -X POST http://localhost:8844/search/agent \
-H "Authorization: Bearer $SERVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_names": ["my_collection", "kb_docs"],
"query_text": "Python 机器学习相关文档",
"max_steps": 5
}'
只保留质量足够高的检索结果时(低于 0.4 的结果被过滤):
curl -X POST http://localhost:8844/search/agent \
-H "Authorization: Bearer $SERVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_names": ["my_collection"],
"query_text": "Python 机器学习相关文档",
"score_threshold": 0.4
}'
需要联网搜索时(Qdrant 数据不足时自动触发):
curl -X POST http://localhost:8844/search/agent \
-H "Authorization: Bearer $SERVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_names": ["my_collection"],
"query_text": "2025年诺贝尔物理学奖获得者是谁",
"enable_web_search": true
}'
请求体:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
collection_names |
list[string] | 是 | - | 目标集合名称列表 |
query_text |
string | 是 | - | 自然语言查询 |
max_steps |
int | 否 | 10 | 最大推理步数(上限 20) |
fusion_method |
string | 否 | rrf | Agent 混合检索融合算法:rrf 或 dbsf,作用于内部 hybrid_search / qa_match 工具。dbsf 分数区分度更好,适合配合 score_threshold 过滤(建议 0.4~0.6) |
rrf_k |
integer | 否 | null(引擎回落 2) | RRF 排序常数 k,作用于内部 hybrid_search / qa_match 工具。默认回落引擎 k=2(Qdrant 官方默认);评测方案 rrf_k60 可传 60,值越小头部优势越明显。仅 fusion_method=rrf 时生效 |
enable_rerank |
bool | 否 | true | 检索后是否用 reranker 重排(作用于内部 hybrid_search 工具)。检索阶段按 round(limit×1.25) 过采样候选、重排后裁剪回 limit 条;重排后分数为 relevance_score,score_threshold 对其生效。未配置 reranker 时自动降级为不重排;reranker 调用失败时回退原始排序(前 limit 条,score_threshold 按原始分数过滤)。候选中文档序列化文本超 3000 字时同样跳过重排(超长文档重排成本高,回退原始排序,score_threshold 按原始分数过滤)。qa_match 工具为精确问答对匹配,不参与重排 |
score_threshold |
float | 否 | null | 检索结果最低匹配分数(0.0-1.0),低于此值的结果被过滤。默认 rrf 融合(w=[2,1])下:稠密单路第一 ≈ 0.67,稀疏单路第一 ≈ 0.33,建议 ≤0.3;dbsf 融合下为相对本次最佳的比例,建议 0.4~0.6。重排成功时按 relevance_score 过滤;重排被跳过/失败时按原始(融合/相似度)分数过滤 |
instructions |
string | 否 | null | 用户自定义指令,注入 system prompt 引导 Agent 行为(最长 30000 字符),优先级高于默认策略 |
enable_web_search |
bool | 否 | false | 是否启用联网搜索。启用时 Agent 可在 Qdrant 数据不足时自动调用网络搜索引擎获取补充信息。服务端未配置 WEB_SEARCH_API_KEY 时此项无效(工具不注册、提示词不注入),请求是否开启都一样 |
llm_params |
object | 否 | null | LLM 调用参数覆盖,直接透传至 OpenAI SDK。常见键: temperature, max_tokens, top_p, reasoning_effort, frequency_penalty, presence_penalty, seed, stop 等 |
timeout |
int | 否 | null | Agent 执行超时秒数(1-300,默认由 AGENT_TIMEOUT 环境变量决定) |
响应:
{
"success": true,
"data": {
"content": "根据对 my_collection 和 kb_docs 集合的检索,找到以下 Python 机器学习相关文档:...",
"steps": 3,
"collections_searched": ["my_collection", "kb_docs"],
"usage": {
"total_tokens": 1500,
"prompt_tokens": 1000,
"completion_tokens": 500,
"cached_tokens": 200
}
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
content |
string | AI 基于检索结果生成的自然语言回答 |
steps |
int | 实际推理步数 |
collections_searched |
list[string] | Agent 实际搜索过的集合列表 |
usage |
object/null | Token 使用统计(total_tokens / prompt_tokens / completion_tokens / cached_tokens),LLM 未返回时为 null |
在 QA 集合中通过语义向量 + BM25 关键词混合检索,匹配最相关的问答对:
curl -X POST http://localhost:8844/search/qa-match \
-H "Authorization: Bearer $SERVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "faq_collection",
"question": "如何重置密码",
"top_k": 3
}'
请求体:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
collection_name |
string | 是 | - | QA 集合名称 |
question |
string | 是 | - | 用户问题 |
top_k |
int | 否 | 3 | 最多返回匹配数 |
score_threshold |
float | 否 | null | 最低匹配分数(0.0-1.0) |
QA 集合需要在创建时指定
"type": "qa",写入数据时每条记录 payload 必须包含answer字段(question可选)。通过POST /vectors/upsert-text写入时会自动校验 payload 完整性。
响应:
{
"success": true,
"data": {
"matches": [
{"question": "怎么重置密码", "answer": "在登录页面点击'忘记密码'...", "score": 0.92},
{"question": "忘记密码怎么办", "answer": "可以通过邮箱验证重置密码...", "score": 0.78}
],
"total": 2
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
question |
string | 匹配到的问题 |
answer |
string | 对应答案 |
score |
float | 匹配分数 |
实现 Dify 外部知识库 API 协议,对接 Dify 知识库插件。
POST /dify/retrieval
Auth: Bearer $DIFY_API_KEY
如果知识库集合启用了稀疏向量索引,
/dify/retrieval自动走 Dense + Sparse BM25 混合检索(RRF 融合),效果与/search/hybrid一致。集合未启用稀疏向量时自动降级为纯语义搜索。
curl -X POST http://localhost:8844/dify/retrieval \
-H "Authorization: Bearer $DIFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"knowledge_id": "my_collection",
"query": "什么是向量数据库",
"retrieval_setting": {
"top_k": 5,
"score_threshold": 0.5
},
"metadata_condition": {
"logical_operator": "and",
"conditions": [
{"name": "category", "comparison_operator": "is", "value": "database"}
]
}
}'
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
knowledge_id |
string | 是 | 知识库 ID(对应 Qdrant 集合名) |
query |
string | 是 | 查询文本 |
retrieval_setting |
object | 是 | 检索参数 |
metadata_condition |
object | 否 | 元数据过滤条件 |
retrieval_setting:
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
top_k |
int | 1-100 | 最大返回数 |
score_threshold |
float | 0.0-1.0 | 最低相似度阈值 |
metadata_condition:
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
logical_operator |
string | "and" |
条件组合方式,支持 "and" / "or" |
conditions |
list | 必填 | 过滤条件列表 |
condition:
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string | payload 字段名 |
comparison_operator |
string | 比较运算符(见下表) |
value |
string/int/list | 比较值 |
支持的比较运算符:
| 运算符 | 说明 | value 类型 |
|---|---|---|
is / = |
等于 | string/int |
is not |
不等于 | string/int |
contains / start with / end with |
文本匹配 | string |
not contains |
文本不匹配 | string |
in |
在列表中 | list[str] |
not in |
不在列表中 | list[str] |
empty |
字段为空 | — |
not empty |
字段不为空 | — |
< / <= / > / >= |
数值比较 | int |
before |
日期之前 | string (日期) |
after |
日期之后 | string (日期) |
{
"records": [
{
"content": "向量数据库是专门存储和检索高维向量的数据库系统...",
"score": 0.95,
"title": "向量数据库介绍",
"metadata": {
"category": "database",
"source": "docs"
}
}
]
}
| 字段 | 类型 | 说明 |
|---|---|---|
content |
string | 检索到的文本内容 |
score |
float | 相似度分数 |
title |
string | 文档标题 |
metadata |
dict | 附加元数据 |
注意:Dify 接口错误返回 HTTP 200,通过
error_code区分。
{
"error_code": 2001,
"error_msg": "知识库 my_collection 不存在"
}
| Code | 说明 |
|---|---|
1001 |
Authorization header 格式错误 |
1002 |
认证失败(Key 不匹配) |
2001 |
知识库(集合)不存在 |
3001 |
查询参数无效 |
3002 |
内部服务错误 |
服务同时支持 MCP (Model Context Protocol) 协议,通过 JSON-RPC over HTTP 访问。
POST /mcp
使用 MCP_API_KEY 环境变量中配置的密钥,通过 Bearer Token 认证:
Authorization: Bearer <MCP_API_KEY>
MCP 接口基于 Streamable HTTP 传输,支持两种接入方式:
方式一:HTTP 调用(Streamable HTTP)
# 1. 初始化会话
curl -X POST http://localhost:8844/mcp \
-H "Authorization: Bearer $MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {"name": "my-client", "version": "1.0"}
},
"id": 1
}'
# 2. 获取会话 ID(从响应头 MCP-Session-Id),之后复用
# 列出所有工具
curl -X POST http://localhost:8844/mcp \
-H "Authorization: Bearer $MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Mcp-Session-Id: <session_id>" \
-d '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}'
# 3. 调用工具(以语义搜索为例)
curl -X POST http://localhost:8844/mcp \
-H "Authorization: Bearer $MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Mcp-Session-Id: <session_id>" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "qdrant_search",
"arguments": {
"collection_name": "my_docs",
"query": "编程语言",
"limit": 5
}
},
"id": 3
}'
方式二:stdio 模式(CLI 直接运行)
uv run qdrant-mcp
| 工具名 | 分类 | 说明 |
|---|---|---|
qdrant_list_collections |
集合管理 | 列出所有集合 |
qdrant_get_collection_info |
集合管理 | 获取集合详情 |
qdrant_create_collection |
集合管理 | 创建集合 |
qdrant_delete_collection |
集合管理 | 删除集合 |
qdrant_update_collection |
集合管理 | 更新集合配置 |
qdrant_upsert_vectors |
向量操作 | 批量写入向量(points_json,单次 ≤1000 点) |
qdrant_upsert_text |
向量操作 | 文本自动向量化写入(points_json,单次 ≤100 条) |
qdrant_query_vectors |
向量操作 | 向量相似度搜索 |
qdrant_scroll_vectors |
向量操作 | 分页滚动遍历 |
qdrant_retrieve_vectors |
向量操作 | 按 ID 查询 |
qdrant_delete_vectors |
向量操作 | 批量删除 |
qdrant_count_vectors |
向量操作 | 统计数量 |
qdrant_set_payload |
向量操作 | 设置 payload |
qdrant_search |
搜索 | 语义搜索 |
qdrant_hybrid_search |
搜索 | 混合搜索(dense+sparse) |
qdrant_agent_search |
搜索 | Agent 智能问答 |
qdrant_qa_match |
搜索 | QA 问答对匹配 |
qdrant_create_field_index |
集合管理 | 创建 payload 字段索引 |
qdrant_delete_field_index |
集合管理 | 删除 payload 字段索引 |