mirror of
https://github.com/modelstudioai/cli.git
synced 2026-09-14 19:49:23 +08:00
zeyu.fz
a95ad7242b
- 新增知识库管理（kb）命令详解，包含创建、查询、更新、删除和状态监控 - 补充文档（doc）管理命令，包括文件上传、导入状态查询、标签管理等 - 增加数据中心文件（file）管理说明，覆盖文件列表、详情、删除操作 - 完善集合与分类管理（collection/category）命令手册，支持创建、查询、删除等功能 - 详细描述 chunk 管理命令，包括添加、更新、查询和删除操作 - 统一说明通用约定，涵盖鉴权、全局参数、输出格式、确认机制及干跑模式 - 提供丰富参数说明、输出格式及使用示例，提升 CLI 使用体验和易用性
219 lines
8.2 KiB
Markdown
219 lines
8.2 KiB
Markdown
# 检索与对话命令手册
|
||
|
||
以下命令通过检索服务（agent）消费知识库。`search` 用于语义检索，`chat` 用于多轮对话。`retrieve` 已废弃。
|
||
|
||
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
|
||
|
||
---
|
||
|
||
#### `kscli retrieve`
|
||
|
||
从知识库检索（已废弃，请用 `search` 替代）。
|
||
|
||
**用法**
|
||
|
||
```bash
|
||
kscli retrieve --index-id <id> --query <text> [flags]
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| ------------------------------- | ------ | ---- | --------------------------------------------------- |
|
||
| `--index-id <id>` | string | 是 | 知识库 ID |
|
||
| `--query <text>` | string | 是 | 检索查询文本 |
|
||
| `--dense-similarity-top-k <n>` | number | 否 | 稠密检索 top K |
|
||
| `--sparse-similarity-top-k <n>` | number | 否 | 稀疏检索 top K |
|
||
| `--rerank` | switch | 否 | 启用 rerank |
|
||
| `--rerank-top-n <n>` | number | 否 | rerank 返回 top N 结果 |
|
||
| `--rerank-model <name>` | string | 否 | rerank 模型名，如 `qwen3-rerank-hybrid` |
|
||
| `--rerank-mode <mode>` | string | 否 | rerank 模式：`qa`、`similar` 或 `custom` |
|
||
| `--rerank-instruct <text>` | string | 否 | 自定义 rerank 指令（`--rerank-mode custom` 时使用） |
|
||
| `--top-k <n>` | number | 否 | 返回结果数（已废弃，用 `--rerank-top-n` 替代） |
|
||
|
||
**输出**
|
||
|
||
text/quiet 模式：
|
||
|
||
```
|
||
[1] (score: 0.9512)
|
||
检索到的文本内容...
|
||
|
||
[2] (score: 0.8734)
|
||
另一段文本内容...
|
||
```
|
||
|
||
> 无结果时输出 `No results found.`
|
||
|
||
json 模式：返回 API 原始响应。
|
||
|
||
**注意事项**
|
||
|
||
- **已废弃**，推荐使用 `search` 命令。`search` 通过 agent_id 驱动检索策略，支持更多高级特性。
|
||
- `--top-k` 已废弃，使用 `--rerank-top-n` 替代，传入 `--top-k` 会输出 stderr 警告。
|
||
- 此命令直接用 `--index-id` 检索，不需要创建检索服务。
|
||
|
||
**示例**
|
||
|
||
```bash
|
||
# 基础检索
|
||
kscli retrieve --index-id idx-xxx --query "How to use Alibaba Cloud Bailian" --workspace-id ws-xxx
|
||
|
||
# 启用 rerank
|
||
kscli retrieve --index-id idx-xxx --query "RAG retrieval" --rerank --rerank-model qwen3-rerank-hybrid
|
||
```
|
||
|
||
---
|
||
|
||
#### `kscli search`
|
||
|
||
对知识库执行语义检索（RAG 检索）。
|
||
|
||
**用法**
|
||
|
||
```bash
|
||
kscli search --query <text> --agent-id <id> [flags]
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --------------------------- | ------ | ---- | ------------------------------------------------------------------- |
|
||
| `--query <text>` | string | 是 | 检索查询文本（不可为空） |
|
||
| `--agent-id <id>` | string | 是 | 检索服务 ID（在控制台知识检索页面获取，或通过 `service list` 查看） |
|
||
| `--agent-version <version>` | string | 否 | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本 |
|
||
| `--image <url>` | array | 否 | 图片 URL（可重复），用于多模态检索 |
|
||
|
||
**参数约束**
|
||
|
||
- `--query` 不可为空（API 要求 `minLength: 1`）
|
||
|
||
**输出**
|
||
|
||
text/quiet 模式：
|
||
|
||
```
|
||
[1] (score: 0.9512)
|
||
检索到的文本内容...
|
||
|
||
[2] (score: 0.8734)
|
||
另一段文本内容...
|
||
```
|
||
|
||
> 无结果时输出 `No results found.`
|
||
|
||
json 模式：返回 API 原始响应，`data.nodes[]` 包含检索结果。
|
||
|
||
**注意事项**
|
||
|
||
- 检索范围和策略（多知识库加权、路由、rerank 等）由 `--agent-id` 对应的服务配置驱动。只需 `--query` 和 `--agent-id` 即可调用。
|
||
- `--agent-version beta` 调试草稿配置进行调试，部署前验证效果。
|
||
- 与 `retrieve` 的区别：`search` 通过 agent_id 间接驱动检索策略（支持多知识库、路由、rerank 等），`retrieve` 直接操作 index_id 且功能较少。
|
||
|
||
**示例**
|
||
|
||
```bash
|
||
# 基础检索
|
||
kscli search --query "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
|
||
|
||
# 多模态检索（带图片）
|
||
kscli search --query "describe this image" --agent-id aid-xxx --workspace-id ws-xxx --image https://example.com/img.jpg
|
||
|
||
# 调试草稿版本
|
||
kscli search --query "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
|
||
```
|
||
|
||
---
|
||
|
||
#### `kscli chat`
|
||
|
||
与知识库进行 RAG 对话（流式输出）。
|
||
|
||
**用法**
|
||
|
||
```bash
|
||
kscli chat --message <text> --agent-id <id> [flags]
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --------------------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||
| `--message <text>` | array | 是¹ | 消息文本（可重复）。支持 `role:content` 前缀设置角色（如 `user:hello`），默认角色为 `user`。也支持完整 JSON 对象传递结构化消息 |
|
||
| `--agent-id <id>` | string | 是 | Q&A 服务 ID（在控制台知识问答页面获取，或通过 `service list --scene chat` 查看） |
|
||
| `--agent-version <version>` | string | 否 | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本 |
|
||
| `--image <url>` | array | 否 | 图片 URL（可重复）。附加到最后一条 user 消息作为多模态内容 |
|
||
|
||
> ¹ `--message` 或 `--image` 至少提供其一。纯图片查询可以只传 `--image`（CLI 会自动创建空 user 消息承载图片）。
|
||
|
||
**参数约束**
|
||
|
||
- `--message` 或 `--image` 至少提供一个
|
||
- `--image` 不能与已包含 `image_url` 内容部分的消息同时使用
|
||
|
||
**输出**
|
||
|
||
**TTY text 模式**（实时流式）：
|
||
|
||
```
|
||
🔍 Retrieving...
|
||
✍️ Generating...
|
||
这是AI生成的回答内容，逐字流式输出...
|
||
```
|
||
|
||
> 进度标签由 SSE `step_change` 事件驱动：`tool_calling`（检索中）→ `plan_start`（规划中）→ `generation_start`（生成中）。
|
||
|
||
**非 TTY text 模式**（缓冲输出）：
|
||
|
||
```
|
||
完整的回答文本...
|
||
```
|
||
|
||
**json 模式**（`--output json`）：
|
||
|
||
```json
|
||
{
|
||
"answer": "完整的回答文本...",
|
||
"request_id": "xxx"
|
||
}
|
||
```
|
||
|
||
quiet 模式：输出完整的回答文本。
|
||
|
||
**注意事项**
|
||
|
||
- API 仅支持 SSE 流式响应。TTY 环境下实时打印 token；非 TTY 环境缓冲后输出完整文本。
|
||
- SSE 事件生命周期：`tool_calling` → `tool_return` → `plan_start` → `planning` → `plan_end` → `generation_start` → `generating` → `generation_end`。`tool_calling` → `tool_return` 可能循环多次。
|
||
- 多轮对话：用 `--message "user:..."` 和 `--message "assistant:..."` 传递对话历史。
|
||
- `--agent-version beta` 调用草稿配置进行调试。
|
||
- `--image` 附加到最后一条 user 消息上。如果消息中已包含 `image_url` 内容部分，则不能再用 `--image`。
|
||
- `--verbose` 模式下，所有 SSE 事件详情会输出到 stderr。
|
||
|
||
**示例**
|
||
|
||
```bash
|
||
# 单轮对话
|
||
kscli chat --message "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
|
||
|
||
# 多轮对话（带历史）
|
||
kscli chat \
|
||
--message "user:What is RAG?" \
|
||
--message "assistant:RAG is retrieval-augmented generation..." \
|
||
--message "How does it work?" \
|
||
--agent-id aid-xxx --workspace-id ws-xxx
|
||
|
||
# 多模态对话（带图片）
|
||
kscli chat \
|
||
--message "Describe these images" \
|
||
--image https://example.com/a.png \
|
||
--image https://example.com/b.png \
|
||
--agent-id aid-xxx --workspace-id ws-xxx
|
||
|
||
# 调试草稿版本
|
||
kscli chat --message "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
|
||
```
|
||
|
||
---
|
||
|
||
← [返回总览](./kscli-cli-guide.md)
|