API 文档

认证

所有管理/查询接口使用 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 内部错误

Filter 模型

/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
}

按 ID 查询

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

为点设置 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
}

混合搜索(语义 + 关键词 BM25)

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 起过滤弱相关。

Agent 智能搜索

使用 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 匹配

在 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 检索

实现 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 协议接口

服务同时支持 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 字段索引