搜索 - Conare

POST /namespaces/:namespace/query 按语义和关键词搜索命名空间；Conare 会对最佳匹配进行重排序，并为每个文档返回能回答问题的段落。

curl https://api.conare.ai/namespaces/docs/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "top_k": 5, "filter": {"team": "support"}}'

const results = await docs.query("how do refunds work?", {
  topK: 5,
  filter: { team: "support" },
});

Response

{
  "results": [
    {
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3192,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "took_ms": 62
}

选项

选项	类型	作用
`query`	string，必填	问题，最多 8,000 个字符
`top_k`	integer，默认 10	返回的结果数，1-500
`filter`	object	元数据过滤器
`user`	string	仅限该用户的文档
`user_prefix`	string	仅限以此开头的用户，如 `tenant-7:`
`answer`	boolean，默认 `false`	同时生成答案
`rerank`	boolean，默认 `true`	对最佳匹配进行重排序；`false` 更快
`rerank_depth`	integer，默认 20	参与重排序的靠前段落数，1-1,000
`hops`	integer，默认 1	`2` 会从最佳结果出发再次搜索（两跳）
`retrievers`	array，默认 `["vector", "keyword"]`	`vector`（语义）和 `keyword` 中的 1 个或 2 个
`exclude_ids`	array	最多 10,000 个要排除的文档 id
`max_results`	integer	分页浏览最多 1,000 个结果，使用自定义模型时最多 5,000 个
`cursor`	string	上一页的 `next_cursor`

完整 schema：查询命名空间。

响应

字段	含义
`results`	最佳结果在前，每个文档一个
`results[].id`、`metadata`、`user`	文档自身的值
`results[].text`	其能回答问题的段落，最佳的排在最前：最佳段落及最多两个匹配度相近的段落，每个最多约 3,000 字节，不连续的段落之间以仅含 `…` 的一行分隔；完整内容请获取文档
`results[].score`	越高越好；仅在同一查询内比较
`results[].reranked`	是否经过重排序器打分；未重排序的结果排在最后
`answer`	答案，需设置 `answer: true`
`next_cursor`	使用 `max_results` 时为下一页的 `cursor`；最后一页不包含
`took_ms`	搜索耗时，单位为毫秒

答案

"answer": true 会基于最佳段落生成答案，大约多花 2 秒。

Response

{
  "answer": "Refunds are available for 30 days (source dated 2026-10-21). No further details on the refund process, conditions, or method were found in this search.",
  "results": [ ... ],
  "took_ms": 1546
}

由语言模型根据找到的段落撰写答案；请参阅隐私政策。
如果该模型不可用，您将获得不含 answer 的结果。

两跳

"hops": 2 会从最佳结果出发再次搜索，适用于答案需要两个文档中事实的问题。

curl

curl https://api.conare.ai/namespaces/films/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "where was the director of The Long Harbor born?", "hops": 2}'

它会增加约 0.3 秒：请用于需要串联事实的问题。
与 rerank: false 或 max_results 同用，或用于自定义模型的命名空间时，返回 400 invalid_request。

分页

步骤	发送
第一页	`query`、`max_results`（一次排序的数量）和 `top_k`（每页大小）
后续页	仅 `cursor`（上一个 `next_cursor`）和 `top_k`
最后一页	没有 `next_cursor`

游标有效期为 15 分钟。SDK 的 queryPages() 会读取所有页。

搜索所有命名空间

POST /query 在最多 100 个命名空间中执行相同请求，并统一重排序；prefix 仅限名称以其开头的命名空间。

curl

curl https://api.conare.ai/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "prefix": "acme-"}'

Response

{
  "namespaces": ["acme-docs"],
  "results": [
    {
      "namespace": "acme-docs",
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3471,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "skipped_namespaces": [],
  "took_ms": 64
}

选项或字段	此处
`prefix`	仅限名称以此开头的命名空间
`rerank_depth`	默认 60，1-1,000
`exclude_ids`	写作 `namespace/id`
`results[].namespace`	结果所属的命名空间
`namespaces`、`skipped_namespaces`	已搜索的命名空间，以及超出前 100 个的命名空间

hops 在此同样适用。完整 schema：查询所有命名空间。

降级结果

如果搜索的某一部分失败，查询仍会成功，Conare-Degraded 标头会说明跳过了什么。

值	含义
`rerank`、`rerank-partial`	部分或全部结果未经重排序（`reranked: false`）
`embed`	仅按关键词搜索
`keyword`、`keyword-terms`	查询过长，关键词搜索无法读取全部内容
`embed-next`	命名空间的部分内容无法搜索
`cursor`	没有 `next_cursor`；请重新搜索以获取更多页
`embed-busy`、`embed-fallback`	比平时慢；结果不受影响
`answer`	没有答案，仅有结果

如果完全无法搜索，查询返回 503。

快速开始

核心

文件

同步

模型

工具

搜索

选项

响应

答案

两跳

分页

搜索所有命名空间

降级结果

​选项

​响应

​答案

​两跳

​分页

​搜索所有命名空间

​降级结果

选项

响应

答案

两跳

分页

搜索所有命名空间

降级结果