# 搜索 (/docs/api/native/knowledge/search)



[快速开始：官方 Python SDK](/docs/cloud/services/knowledge/quickstart)

[基础地址与鉴权](/docs/api/native/knowledge)

路径中的 ID 使用已有资源的 ID。示例中的环境变量由调用者设置。

## 搜索知识库 [#搜索知识库]

`POST /knowledge/v1/vector_stores/{vector_store_id}/search`

按分段返回，同一文件可出现多次。最多 50 条，没有下一页。

### 参数 [#参数]

| 名称                | 位置与类型        | 说明                                   |
| ----------------- | ------------ | ------------------------------------ |
| vector\_store\_id | path: string | 必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1 |

### 请求体 [#请求体]

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| query | string / string[] | 必填; 非空白文本；多个查询以换行连接后共同搜索。 |
| filters | object / object / object | 可选; 按类型严格匹配文件属性；根条件以下最多嵌套 20 层。 |
| filters (1).type | "eq" / "ne" / "gt" / "gte" / "lt" / "lte" | 必填; eq 等于，ne 不等于，gt 大于，gte 大于等于，lt 小于，lte 小于等于；属性必须存在且值类型一致。 |
| filters (1).key | string | 必填; 要比较的文件属性原始键名，标点也是键名的一部分。; 最短字符数: 1 |
| filters (1).value | string / number / boolean | 必填; 不进行类型转换的比较值。 |
| filters (2).type | "in" / "nin" | 必填; in 匹配数组中的值；nin 匹配不在数组中的值。属性不存在时均不匹配。 |
| filters (2).key | string | 必填; 要比较的文件属性原始键名，标点也是键名的一部分。; 最短字符数: 1 |
| filters (2).value | string / number[] | 必填; 不进行类型转换的字符串或数值成员列表。 |
| filters (3).type | "and" / "or" | 必填; and 要求所有子条件匹配；or 要求至少一个子条件匹配。 |
| filters (3).filters | object / object / object[] | 必填; 按选定 and/or 运算符组合的非空子条件列表。; 最少条数: 1 |
| filters (3).filters[] | object / object / object | 递归使用同一筛选结构，嵌套上限 20 层。 |
| max_num_results | integer | 可选; 最多返回的分段数，不是不同文件数。; 最小: 1; 最大: 50; 默认: 10 |
| rewrite_query | boolean | 可选; 支持: 为 true 时，先用该库 query_rewrite 角色的模型把每条查询改写为简洁的检索查询；检索使用改写结果，search_query 返回改写后的查询。每次改写是一次小模型调用，按模型用量计费。改写失败、超时（5 秒）或为空时，该条查询回退为原文，搜索照常完成。省略或为 false 时不调用模型。 |
| next_page | string | 可选; 不生效: 搜索不支持翻页；提供游标不生效。 |
| ranking_options | object | 可选; 控制结果排序与纳入结果的最低分数。 |
| ranking_options.ranker | "none" / "auto" / "default-2024-11-15" | 可选; 只有 default-2024-11-15 请求重排；none、auto 和省略时使用初始排序。尚未单独实测重排效果。 |
| ranking_options.score_threshold | number | 可选; 最低分数；分数不是相关性概率。尚未单独实测阈值效果。; 最小: 0; 最大: 1; 默认: 0 |
| ranking_options.hybrid_search | object | 可选; Praxis 扩展。两个权重均须提供，必须非负且总和大于 0；省略时使用 0.7 / 0.3。; Praxis 扩展 |
| ranking_options.hybrid_search.embedding_weight | number | 必填; 语义检索相对权重；零表示禁用语义检索。; 最小: 0; 默认: 0.7 |
| ranking_options.hybrid_search.text_weight | number | 必填; 关键词检索相对权重；零表示禁用关键词检索。; 最小: 0; 默认: 0.3 |
| praxis | object | 可选; 设置 explain=true 返回分数和关键词解释。; Praxis 扩展 |
| praxis.explain | boolean | 可选; true 请求每条结果的分数、排名与关键词解释。; 默认: false |

### 请求示例 [#请求示例]

```bash
curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/search" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"query\":\"When will I receive my refund?\",\"max_num_results\":5,\"praxis\":{\"explain\":true}}"
```

### 响应 [#响应]

HTTP 200

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | "vector_store.search_results.page" | 必有; 对象标记；vector_store.search_results.page 表示搜索结果页。 |
| search_query | string[] | 必有; 实际用于检索的查询，与输入一一对应；rewrite_query 为 true 时为改写后的查询，否则原样返回。 |
| data | object[] | 必有; 每个命中分段返回一条；同一 file_id 可重复出现。 |
| data[].file_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| data[].filename | string | 必有; 命中文件的源文件名。 |
| data[].score | number | 必有; 此分段的相关排序分数，限制在 0 到 1；不是概率。; 最小: 0; 最大: 1 |
| data[].attributes | object / null | 必有; 用于筛选的当前文件属性；未设置时为 null。 |
| data[].content | object[] | 必有; 命中分段文本与源文坐标；原生结果每条包含一个分段。 |
| data[].content[].type | "text" | 必有; text 表示提取出的文本分段。 |
| data[].content[].text | string | 必有; 命中分段的提取文本，可能与相邻分段重叠。 |
| data[].content[].chunk_id | string | 可选; 资源 ID。; 最短字符数: 1 |
| data[].content[].page | integer / null | 可选; 此段起点所在的源文页码，从一开始；无页码映射时为 null。 |
| data[].content[].span | integer[] | 可选; 以 UTF-16 代码单元表示的起止位置。; 最少条数: 2; 最多条数: 2 |
| data[].praxis | object | 可选; 原生搜索解释；仅请求 praxis.explain 时返回。 |
| data[].praxis.explain | object | 必有; 每个命中分段的检索分数、排名与匹配词。 |
| data[].praxis.explain.semantic_score | number / null | 必有; 此段语义检索分数；不在语义候选中时为 null。 |
| data[].praxis.explain.keyword_score | number / null | 必有; 此段关键词检索分数；不在关键词候选中时为 null。 |
| data[].praxis.explain.rerank_score | number / null | 必有; 重排模型分数；未重排时为 null。 |
| data[].praxis.explain.semantic_rank | integer / null | 必有; 语义候选中的排名，从一开始；该路未召回时为 null。 |
| data[].praxis.explain.keyword_rank | integer / null | 必有; 关键词候选中的排名，从一开始；该路未召回时为 null。 |
| data[].praxis.explain.rank_before_rerank | integer | 必有; 最小: 1 |
| data[].praxis.explain.query_terms | string[] | 必有; 解释使用的归一化查询词，包括相邻汉字组成的双字词。 |
| data[].praxis.explain.matched_terms | string[] | 必有; 归一化分段文本中出现的查询词。 |
| has_more | boolean | 必有; 过滤后的分段数超过 max_num_results 时为 true；next_page 仍为 null。; 支持:  |
| next_page | null | 必有; 不生效: 恒为 null，没有下一页搜索结果。 |

[错误码与错误对象](/docs/api/native/knowledge/errors)