检索与对话命令

这三个命令用于消费知识库：search 执行语义检索，chat 进行多轮对话，retrieve 直连单个知识库检索但已废弃。鉴权、业务空间 ID、全局参数、输出格式等通用约定见 CLI 概述。以下示例默认已通过配置文件设置业务空间 ID，retrieve 不需要业务空间 ID。

命令选择

命令	入参	适用场景
`search`	`--agent-id`	语义检索。检索范围与策略由服务配置驱动，支持多知识库、路由、重排
`chat`	`--agent-id`	多轮问答。流式返回模型生成的答案
`retrieve`	`--index-id`	已废弃。直连单个知识库，功能受限且不再迭代

kscli search

对知识库执行语义检索。

kscli search --query <text> --agent-id <id> [flags]

参数

参数	类型	必填	说明
`--query <text>`	string	是	检索查询文本，不可为空
`--agent-id <id>`	string	是	检索服务 ID，通过 `service list --scene search` 查看
`--agent-version <version>`	string	否	服务版本，`beta`（草稿）或已发布版本号。默认调用最新已发布版本
`--image <url>`	array	否	图片 URL，可重复传入，用于多模态检索

输出

[1] (score: 0.9512)
检索到的文本内容…

[2] (score: 0.8734)
另一段文本内容…

无结果时输出 No results found.。json 模式返回完整结果，包含每条检索结果及其分数和元数据。 注意事项

检索范围和策略（多知识库加权、路由、重排等）由 --agent-id 对应的服务配置驱动，因此只需传 --query 和 --agent-id，无需在命令中重复指定检索参数。
--agent-version beta 调用草稿配置，用于发布前验证调优效果。

示例

# 基础检索
kscli search --query "什么是 RAG" --agent-id aid-xxx

# 多模态检索
kscli search --query "描述这张图" --agent-id aid-xxx --image https://example.com/img.jpg

# 验证草稿配置
kscli search --query "测试" --agent-id aid-xxx --agent-version beta

kscli chat

与知识库进行 RAG 对话，流式输出。

kscli chat --message <text> --agent-id <id> [flags]

参数

参数	类型	必填	说明
`--message <text>`	array	是	消息文本，可重复传入。支持 `role:content` 前缀指定角色（如 `user:hello`），默认角色为 `user`，遵循 OpenAI 消息格式
`--agent-id <id>`	string	是	问答服务 ID，通过 `service list --scene chat` 查看
`--agent-version <version>`	string	否	服务版本，`beta`（草稿）或已发布版本号。默认调用最新已发布版本
`--image <url>`	array	否	图片 URL，可重复传入，附加到最后一条 user 消息

--message 与 --image 至少提供一个。纯图片查询可以只传 --image。--image 不能与已包含图片内容的结构化消息同时使用。输出终端交互环境下实时流式打印，进度标签随服务端处理阶段变化：

🔍 Retrieving...
✍️ Generating...
生成的回答内容逐字输出…

输出被重定向或通过管道传递时，缓冲后一次性输出完整文本。 json 模式返回：

{
  "answer": "完整的回答文本…",
  "request_id": "xxx"
}

quiet 模式输出完整回答文本。 注意事项

多轮对话通过重复传入 --message 并用 role: 前缀标注角色来传递历史。
--verbose 会将流式过程的详细事件输出到 stderr，便于排查中断或异常。
报错 Chat API error 时，检查 --agent-id 是否存在、服务是否已发布、API Key 是否有效。错误码和信息由服务端原样返回。

示例

# 单轮对话
kscli chat --message "什么是 RAG" --agent-id aid-xxx

# 多轮对话，传递历史
kscli chat \
  --message "user:什么是 RAG" \
  --message "assistant:RAG 是检索增强生成…" \
  --message "它是怎么工作的" \
  --agent-id aid-xxx

# 多模态对话
kscli chat \
  --message "描述这些图片" \
  --image https://example.com/a.png \
  --image https://example.com/b.png \
  --agent-id aid-xxx

# 验证草稿配置
kscli chat --message "测试" --agent-id aid-xxx --agent-version beta

kscli retrieve

从单个知识库直连检索。

此命令已废弃，执行时会输出废弃警告。请改用 search。search 通过 --agent-id 驱动检索策略，支持多知识库、路由、重排等能力；retrieve 直接操作单个知识库 ID，功能受限且不再迭代。

kscli retrieve --index-id <id> --query <text> [flags]

参数

参数	类型	必填	说明
`--index-id <id>`	string	是	知识库 ID
`--query <text>`	string	是	检索查询文本
`--dense-similarity-top-k <n>`	number	否	语义检索召回数量
`--sparse-similarity-top-k <n>`	number	否	关键词检索召回数量
`--rerank`	switch	否	启用重排
`--rerank-top-n <n>`	number	否	重排后返回的结果数
`--rerank-model <name>`	string	否	重排模型名称，如 `qwen3-rerank-hybrid`
`--rerank-mode <mode>`	string	否	重排模式，`qa`、`similar` 或 `custom`
`--rerank-instruct <text>`	string	否	自定义重排指令，`--rerank-mode custom` 时使用
`--top-k <n>`	number	否	返回结果数。已废弃，改用 `--rerank-top-n`

输出格式与 search 相同。无结果时输出 No results found.。 注意事项

此命令不需要业务空间 ID，直接用 --index-id 检索，无需创建检索服务。
--top-k 已废弃，传入会在 stderr 输出警告，请改用 --rerank-top-n。

示例

# 基础检索
kscli retrieve --index-id idx-xxx --query "如何配置切片策略"

# 启用重排
kscli retrieve --index-id idx-xxx --query "RAG 检索" \
  --rerank --rerank-model qwen3-rerank-hybrid

​命令选择

​kscli search

​kscli chat

​kscli retrieve

命令选择

kscli search

kscli chat

kscli retrieve