mirror of
https://github.com/modelstudioai/cli.git
synced 2026-09-14 19:49:23 +08:00
若麒
402 lines
13 KiB
Markdown
402 lines
13 KiB
Markdown
# 检索服务管理命令手册
|
||
|
||
检索服务（也称 agent）是知识库的检索入口。通过 `--agent-id` 在 search/chat 命令中使用。服务有 `chat`（问答）和 `search`（检索）两种场景。
|
||
|
||
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
|
||
|
||
---
|
||
|
||
#### `kscli service list`
|
||
|
||
列出工作区中的检索/Q&A 服务。
|
||
|
||
**用法**
|
||
|
||
```bash
|
||
kscli service list --scene <chat|search> [flags]
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| ------------------------ | ------ | ---- | ------------------------------------------------------- |
|
||
| `--scene <chat\|search>` | string | 是 | 服务场景：`chat`（Q&A）或 `search`（检索） |
|
||
| `--status <status>` | string | 否 | 按状态过滤：`draft`、`deployed`（含 edited）、`deleted` |
|
||
| `--name <text>` | string | 否 | 按服务名称模糊过滤 |
|
||
| `--agent-id <id>` | string | 否 | 按精确 agent ID 过滤 |
|
||
| `--index-id <id>` | string | 否 | 按关联知识库 ID 过滤 |
|
||
| `--page-number <n>` | number | 否 | 页码（默认：1） |
|
||
| `--page-size <n>` | number | 否 | 每页条数（默认：10，最大 100） |
|
||
|
||
**参数约束**
|
||
|
||
- `--scene` 只能是 `chat` 或 `search`
|
||
- `--status` 只能是 `draft`、`deployed`、`deleted`
|
||
- `--page-size` 范围 1-100
|
||
|
||
**输出**
|
||
|
||
text 模式：
|
||
|
||
```
|
||
aid-xxx deployed 2 my-qa (kb: my-kb)
|
||
total: 1
|
||
Use an agent_id above with the chat command.
|
||
```
|
||
|
||
> 最后一行根据 scene 自动提示用 `search` 还是 `chat` 命令消费。
|
||
|
||
quiet 模式：每行一个 `agent_id`。
|
||
|
||
json 模式：返回 API 原始响应。
|
||
|
||
**注意事项**
|
||
|
||
- 服务端要求 `--scene` 必填，要查看两种场景的服务需分别执行。
|
||
|
||
**示例**
|
||
|
||
```bash
|
||
# 列出 chat 服务
|
||
kscli service list --scene chat --workspace-id ws-xxx
|
||
|
||
# 只看已部署的检索服务
|
||
kscli service list --scene search --status deployed
|
||
```
|
||
|
||
---
|
||
|
||
#### `kscli service get`
|
||
|
||
查看服务详情，含各版本配置。
|
||
|
||
**用法**
|
||
|
||
```bash
|
||
kscli service get --agent-id <id> [flags]
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --------------------------- | ------ | ---- | --------------------------------------------------------- |
|
||
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
|
||
| `--agent-version <version>` | string | 否 | 指定版本查看（`beta` 或已发布版本号）；不传则返回所有版本 |
|
||
|
||
**输出**
|
||
|
||
text 模式：
|
||
|
||
```
|
||
Basic:
|
||
id: aid-xxx
|
||
name: my-qa
|
||
desc: product Q&A
|
||
scene: chat
|
||
status: deployed
|
||
Version beta:
|
||
desc: draft
|
||
policy: turbo
|
||
model: qwen-max
|
||
temperature: 0.7
|
||
kb: idx-xxx (my-kb)
|
||
Version 1:
|
||
published: 2026-01-01
|
||
...
|
||
```
|
||
|
||
quiet 模式：输出 JSON 格式。
|
||
|
||
json 模式：返回 API 原始响应。
|
||
|
||
**注意事项**
|
||
|
||
- 不传 `--agent-version` 时返回所有版本（beta 草稿 + 已发布版本号）。
|
||
- 版本值原样传递，有效值集合由服务端维护。
|
||
|
||
**示例**
|
||
|
||
```bash
|
||
# 查看服务完整详情
|
||
kscli service get --agent-id aid-xxx --workspace-id ws-xxx
|
||
|
||
# 只看 beta 草稿配置
|
||
kscli service get --agent-id aid-xxx --agent-version beta
|
||
```
|
||
|
||
---
|
||
|
||
#### `kscli service create`
|
||
|
||
创建检索/Q&A 服务，初始状态为 draft，版本为 beta。
|
||
|
||
**用法**
|
||
|
||
```bash
|
||
kscli service create --name <text> --scene <chat|search> [flags]
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| ------------------------ | ------ | ---- | ------------------------------------------------- |
|
||
| `--name <text>` | string | 是 | 服务名称（最多 200 字符，同一场景下工作区内唯一） |
|
||
| `--scene <chat\|search>` | string | 是 | 服务场景：`chat`（Q&A）或 `search`（检索） |
|
||
| `--description <text>` | string | 建议 | 这个服务能回答什么、给谁用（最多 1000 字符） |
|
||
| `--index-id <id>` | string | 否 | 绑定此知识库；其他配置使用服务端默认值 |
|
||
|
||
**参数约束**
|
||
|
||
- `--name` 最多 200 字符
|
||
- `--scene` 只能是 `chat` 或 `search`
|
||
- `--description` 最多 1000 字符；建议填写 —— agent 靠它判断该调用哪个服务
|
||
|
||
**输出**
|
||
|
||
text 模式：
|
||
|
||
```
|
||
created: aid-xxx (status: draft, version: beta)
|
||
Test the draft with --agent-version beta on search/chat, then deploy it to publish.
|
||
```
|
||
|
||
quiet 模式：输出 agent ID。
|
||
|
||
json 模式：返回 API 原始响应。
|
||
|
||
**注意事项**
|
||
|
||
- 不指定 `--index-id` 时，服务端使用默认 agent 配置。
|
||
- beta 草稿可通过 search/chat 的 `--agent-version beta` 测试，部署后才生效。
|
||
- 需要工作区的知识库创建权限。
|
||
|
||
**示例**
|
||
|
||
```bash
|
||
# 创建 Q&A 服务
|
||
kscli service create --name my-qa --scene chat --workspace-id ws-xxx
|
||
|
||
# 创建检索服务并绑定知识库
|
||
kscli service create --name my-search --scene search --index-id idx-xxx
|
||
```
|
||
|
||
---
|
||
|
||
#### `kscli service update`
|
||
|
||
更新服务名称、描述或草稿配置。
|
||
|
||
**用法**
|
||
|
||
```bash
|
||
kscli service update --agent-id <id> [flags]
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| ------------------------------ | ------ | ---- | ---------------------------------------------------------------------------------------- |
|
||
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
|
||
| `--name <text>` | string | 否 | 新名称（最多 200 字符） |
|
||
| `--description <text>` | string | 否 | 新描述（最多 1000 字符） |
|
||
| `--agent-version <version>` | string | 否 | 目标版本（默认：beta 草稿。已发布版本只接受 `--version-desc`） |
|
||
| `--version-desc <text>` | string | 否 | 版本描述 |
|
||
| `--policy <policy>` | string | 否 | Agent 策略：`turbo`（快速）或 `agentic`（多轮） |
|
||
| `--model <name>` | string | 否 | 生成模型代码（须在平台白名单中） |
|
||
| `--temperature <n>` | number | 否 | 采样温度，范围 0-2 |
|
||
| `--max-llm-calls <n>` | number | 否 | 单次请求最大 LLM 调用次数，范围 1-30 |
|
||
| `--enable-session-file <bool>` | string | 否 | 启用会话文件：`true` 或 `false` |
|
||
| `--enable-refusal <bool>` | string | 否 | 启用拒答：`true` 或 `false` |
|
||
| `--enable-anti-leak <bool>` | string | 否 | 启用防泄漏：`true` 或 `false` |
|
||
| `--enable-rich-text <bool>` | string | 否 | 启用富文本输出：`true` 或 `false` |
|
||
| `--enable-citation <bool>` | string | 否 | 启用引用标注：`true` 或 `false` |
|
||
| `--config-file <path>` | string | 否 | JSON 文件替换整个 `agent_config`（含嵌套设置如 `kb_search_configs`）；与标量配置参数互斥 |
|
||
|
||
**参数约束**
|
||
|
||
- 至少提供一个更新项（`--name`/`--description`/`--version-desc`/`--config-file`/标量配置参数），否则报错 "Nothing to update"
|
||
- `--config-file` 与标量配置参数（`--policy`/`--model`/`--temperature` 等）互斥
|
||
- 已发布版本 + 配置变更 → 报错（已发布版本只接受 `--version-desc`）
|
||
- `--name` 最多 200 字符；`--description` 最多 1000 字符
|
||
- `--policy` 只能是 `turbo` 或 `agentic`
|
||
- `--temperature` 范围 0-2
|
||
- `--max-llm-calls` 范围 1-30
|
||
- 布尔参数（`--enable-*`）只能是 `true` 或 `false`
|
||
|
||
**输出**
|
||
|
||
text 模式：
|
||
|
||
```
|
||
updated: aid-xxx
|
||
Draft config changed — verify with --agent-version beta, then deploy.
|
||
```
|
||
|
||
quiet 模式：无输出。
|
||
|
||
json 模式：返回 API 原始响应。
|
||
|
||
**注意事项**
|
||
|
||
- 配置变更只作用于 beta 草稿；已发布版本只接受 `--version-desc`。
|
||
- 标量配置参数采用 read-merge-write：CLI 先读取当前 beta 配置，再合并变更后整体提交（API 是整替换语义）。
|
||
- `--config-file` 替换整个配置，适合设置嵌套字段（如 `kb_search_configs`）。
|
||
- 修改草稿后用 `--agent-version beta` 在 search/chat 上测试，通过后 `service deploy` 发布。
|
||
|
||
**示例**
|
||
|
||
```bash
|
||
# 调整温度
|
||
kscli service update --agent-id aid-xxx --temperature 0.7 --workspace-id ws-xxx
|
||
|
||
# 用 JSON 文件替换整个配置
|
||
kscli service update --agent-id aid-xxx --config-file ./agent-config.json
|
||
|
||
# 给已发布版本 1 加描述
|
||
kscli service update --agent-id aid-xxx --agent-version 1 --version-desc "first stable release"
|
||
```
|
||
|
||
---
|
||
|
||
#### `kscli service deploy`
|
||
|
||
发布 beta 草稿为新版本。
|
||
|
||
**用法**
|
||
|
||
```bash
|
||
kscli service deploy --agent-id <id> [flags]
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| ----------------------- | ------ | ---- | ---------------------- |
|
||
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
|
||
| `--version-desc <text>` | string | 否 | 新版本的描述说明 |
|
||
| `--yes` | switch | 否 | 显式确认执行高风险操作 |
|
||
|
||
**输出**
|
||
|
||
text 模式：
|
||
|
||
```
|
||
deployed: aid-xxx version 2
|
||
```
|
||
|
||
quiet 模式：输出新版本号。
|
||
|
||
json 模式：返回 API 原始响应。
|
||
|
||
**注意事项**
|
||
|
||
- 版本号自动递增，状态变为 `deployed`。
|
||
- 发布影响线上调用方，确认提示会警告。
|
||
- 如果当前状态为 `edited`（已发布后又改了草稿），确认提示会额外警告「发布会覆盖线上行为」。
|
||
- 需要工作区的知识库修改权限。
|
||
|
||
**示例**
|
||
|
||
```bash
|
||
# 发布（交互确认）
|
||
kscli service deploy --agent-id aid-xxx --workspace-id ws-xxx
|
||
|
||
# 带描述并跳过确认
|
||
kscli service deploy --agent-id aid-xxx --version-desc "tuned rerank params" --yes
|
||
```
|
||
|
||
---
|
||
|
||
#### `kscli service delete`
|
||
|
||
删除检索/Q&A 服务（软删除，幂等）。
|
||
|
||
**用法**
|
||
|
||
```bash
|
||
kscli service delete --agent-id <id> [flags]
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| ----------------- | ------ | ---- | ---------------------- |
|
||
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
|
||
| `--yes` | switch | 否 | 显式确认执行高风险操作 |
|
||
|
||
**输出**
|
||
|
||
text 模式：
|
||
|
||
```
|
||
deleted: aid-xxx (status: deleted)
|
||
```
|
||
|
||
quiet 模式：无输出。
|
||
|
||
json 模式：返回 API 原始响应。
|
||
|
||
**注意事项**
|
||
|
||
- 删除不可撤销，`agent_id` 不再可用于 search/chat 调用。
|
||
- API 是幂等的：删除已删除的服务不会报错。
|
||
- 如果服务状态为 `deployed` 或 `edited`，确认提示会额外警告「此服务正在线上运行」。
|
||
- 需要工作区的知识库删除权限。
|
||
|
||
**示例**
|
||
|
||
```bash
|
||
# 删除（交互确认）
|
||
kscli service delete --agent-id aid-xxx --workspace-id ws-xxx
|
||
|
||
# 跳过确认
|
||
kscli service delete --agent-id aid-xxx --yes
|
||
```
|
||
|
||
---
|
||
|
||
#### `kscli service copy`
|
||
|
||
复制服务为新草稿（名称自动加 `copy_` 前缀）。
|
||
|
||
**用法**
|
||
|
||
```bash
|
||
kscli service copy --agent-id <id> [flags]
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| ----------------- | ------ | ---- | ----------------- |
|
||
| `--agent-id <id>` | string | 是 | 源服务（agent）ID |
|
||
|
||
**输出**
|
||
|
||
text 模式：
|
||
|
||
```
|
||
new agent_id: aid-new (name: copy_my-qa, status: draft)
|
||
Test the draft with --agent-version beta on search/chat, then deploy it to publish.
|
||
```
|
||
|
||
quiet 模式：输出新 agent ID。
|
||
|
||
json 模式：返回 API 原始响应。
|
||
|
||
**注意事项**
|
||
|
||
- 副本初始为 beta 草稿，测试后需 deploy 发布。
|
||
- 需要工作区的知识库创建权限。
|
||
|
||
**示例**
|
||
|
||
```bash
|
||
# 复制服务
|
||
kscli service copy --agent-id aid-source --workspace-id ws-xxx
|
||
```
|
||
|
||
---
|
||
|
||
← [返回总览](./kscli-cli-guide.md)
|