V2
语义搜索
使用自然语言查询做向量语义检索，并返回相关页面片段。
语义搜索
适用场景
当你希望用自然语言找内容，而不是只靠关键词精确匹配时，使用这个接口。它适合知识库检索、问答助手、RAG 场景，返回的是与问题最相关的页面片段，而不是页面和数据库的普通搜索结果。
接口信息
| 项目 | 内容 |
|---|---|
| 方法 | POST |
| 路径 | /v2/search/semantic |
| 请求体 | JSON |
| 返回 | list |
| Scope | search.read |
这个接口和标准的 POST /v2/search 不是同一种能力：
POST /v2/search是关键词搜索，返回页面或数据库对象，并支持过滤、排序和游标分页。POST /v2/search/semantic是语义检索，返回search_result片段、相似度分数和命中页面链接。- 两者的请求字段和响应结构都不同，不能互相替代。
权限要求
需要 search.read。如果当前 token 没有这个 scope，请求会返回 403 forbidden。
请求参数
请求示例
{
"query": "如何配置 CI/CD",
"page_size": 3,
"score_threshold": 0.7
}参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
query | string | 是 | 自然语言查询内容。 |
space_id | string | 否 | 指定检索空间；不传时默认使用当前 token 所在空间。 |
page_size | number | 否 | 返回结果数量，默认 10。 |
score_threshold | number | 否 | 相似度阈值，默认 0.0，低于该值的结果会被过滤掉。 |
响应结果
{
"object": "list",
"results": [
{
"object": "search_result",
"page_id": "44444444-4444-4444-8444-444444444444",
"page_title": "CI/CD 配置指南",
"score": 0.92,
"snippet": "项目使用 GitHub Actions 进行持续集成与部署。",
"url": "https://flowus.cn/44444444-4444-4444-8444-444444444444"
}
],
"next_cursor": null,
"has_more": false
}每个结果都表示一个页面命中，通常包含页面标题、片段、分数和可点击地址。
该接口同样返回列表分页语义，next_cursor 表示下一页游标，has_more 表示是否还有后续结果；结果用尽时分别返回 null 和 false。
行为说明或限制
- 这是语义检索，不是关键字搜索；不要把它当成
POST /v2/search的变体来调用。 - 这个接口只接受
query作为必填项，不支持filter、sort、start_cursor这一类标准搜索字段。 page_size会按过滤后的结果直接截断，默认值是10。score_threshold只做数值过滤，低于阈值的结果不会返回。- 如果语义检索暂时不可用，接口会返回空列表，而不是让整个请求失败。