mirror of
https://github.com/modelstudioai/cli.git
synced 2026-09-14 19:49:23 +08:00
zeyu.fz
a6291e00e1
- 升级知识库创建命令，`--description` 参数变为必填，描述知识库内容和用途 - 更新所有相关文档示例，统一加入 `--description` 参数和示例文本 - CLI 校验增强，缺失或超长的描述参数本地报错，避免服务端拒绝 - 优化服务创建命令，推荐填写描述以帮助 agent 选择合适服务 - 多个测试用例添加对描述参数的验证和断言 - 知识库和集合列表中描述信息作为区分同类项目的辅助信息显式展示 - 其他细节调整包括命令帮助及参数说明内容的更新
220 lines
8.4 KiB
Markdown
220 lines
8.4 KiB
Markdown
<div align="center">
|
||
|
||
# Knowledge Studio CLI
|
||
|
||
**阿里云 Model Studio 轻量级 RAG 命令行工具 — 专注知识库检索。**
|
||
|
||
[](https://www.npmjs.com/package/knowledge-studio-cli)
|
||
[](https://nodejs.org)
|
||
[](https://www.typescriptlang.org)
|
||
[](LICENSE)
|
||
|
||
[Knowledge Studio 控制台](https://rag.console.aliyun.com/) · [English](README.md) · [API 文档](https://help.aliyun.com/zh/model-studio/) · [完整 CLI 指南](https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md)
|
||
|
||
</div>
|
||
|
||
## 这是什么？
|
||
|
||
`kscli` 是阿里云 Model Studio (DashScope) 平台的**知识库检索**专用命令行工具，专为 RAG（检索增强生成）场景打造。覆盖知识库全生命周期管理 — 从创建知识库、文档导入到语义检索与对话问答。
|
||
|
||
## 功能特性
|
||
|
||
- **知识库管理** — 创建、更新、删除、查看知识库；查看存储与文档统计信息
|
||
- **文档管理** — 上传文件、从 OSS 导入、跟踪处理状态、打标签、删除文档
|
||
- **检索服务** — 创建、配置、部署、复制和管理检索服务，将知识库绑定到指定模型
|
||
- **Chunk 管理** — 在文档内新增、列出、更新、删除文本分片，实现细粒度内容控制
|
||
- **数据中心** — 管理工作区数据中心的独立文件，在挂载到知识库前进行预处理
|
||
- **集合与分类** — 通过集合组织知识库，通过分类对文档进行标记，实现范围检索
|
||
- **RAG 检索与对话** — 跨知识库语义检索，流式问答返回基于知识的回答
|
||
- **Agent 友好** — 支持 JSON 结构化输出（`--output json`）、预览模式（`--dry-run`）和静默模式（`--quiet`），便于脚本集成
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
npm install -g knowledge-studio-cli
|
||
```
|
||
|
||
> 需要 Node.js >= 18.17。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 1. 创建知识库
|
||
kscli kb create \
|
||
--name "my-kb" \
|
||
--description "我的产品文档知识库" \
|
||
--embedding-model text-embedding-v3 \
|
||
--workspace-id <your-workspace-id>
|
||
|
||
# 2. 上传文档
|
||
kscli doc upload \
|
||
--kb-id <kb-id> \
|
||
--file ./product-docs.pdf \
|
||
--workspace-id <your-workspace-id>
|
||
|
||
# 3. 查看处理状态
|
||
kscli doc status \
|
||
--kb-id <kb-id> \
|
||
--doc-id <doc-id> \
|
||
--workspace-id <your-workspace-id>
|
||
|
||
# 4. 语义检索
|
||
kscli search \
|
||
--query "什么是 Model Studio？" \
|
||
--agent-id <your-agent-id> \
|
||
--workspace-id <your-workspace-id>
|
||
|
||
# 5. 知识库问答（流式输出）
|
||
kscli chat \
|
||
--message "什么是RAG？" \
|
||
--agent-id <your-agent-id> \
|
||
--workspace-id <your-workspace-id>
|
||
```
|
||
|
||
## 命令列表
|
||
|
||
### 知识库管理
|
||
|
||
| 命令 | 说明 |
|
||
| :---------- | :--------------------------- |
|
||
| `kb list` | 列出当前工作区的知识库 |
|
||
| `kb info` | 查看知识库详情 |
|
||
| `kb create` | 创建新知识库 |
|
||
| `kb update` | 更新知识库配置 |
|
||
| `kb delete` | 删除知识库 |
|
||
| `kb stats` | 查看知识库存储与文档统计信息 |
|
||
|
||
### 文档管理
|
||
|
||
| 命令 | 说明 |
|
||
| :--------------- | :---------------------- |
|
||
| `doc list` | 列出知识库中的文档 |
|
||
| `doc upload` | 上传文档到知识库 |
|
||
| `doc status` | 查看文档处理状态 |
|
||
| `doc delete` | 从知识库中删除文档 |
|
||
| `doc tag` | 添加或更新文档标签 |
|
||
| `doc import-oss` | 从 OSS 导入文档到知识库 |
|
||
|
||
### 检索服务
|
||
|
||
| 命令 | 说明 |
|
||
| :--------------- | :--------------------- |
|
||
| `service list` | 列出检索服务 |
|
||
| `service get` | 查看检索服务详情 |
|
||
| `service create` | 创建检索服务 |
|
||
| `service update` | 更新检索服务配置 |
|
||
| `service deploy` | 部署或重新绑定检索服务 |
|
||
| `service delete` | 删除检索服务 |
|
||
| `service copy` | 复制检索服务配置 |
|
||
|
||
### Chunk 管理
|
||
|
||
| 命令 | 说明 |
|
||
| :------------- | :----------------- |
|
||
| `chunk add` | 向文档添加文本分片 |
|
||
| `chunk list` | 列出文档中的分片 |
|
||
| `chunk update` | 更新文本分片 |
|
||
| `chunk delete` | 删除文档中的分片 |
|
||
|
||
### 数据中心文件
|
||
|
||
| 命令 | 说明 |
|
||
| :------------ | :------------------- |
|
||
| `file list` | 列出数据中心文件 |
|
||
| `file get` | 查看数据中心文件详情 |
|
||
| `file delete` | 删除数据中心文件 |
|
||
|
||
### 集合与分类
|
||
|
||
| 命令 | 说明 |
|
||
| :------------------ | :----------------- |
|
||
| `collection create` | 在知识库中创建集合 |
|
||
| `collection get` | 查看集合详情 |
|
||
| `category list` | 列出知识库中的分类 |
|
||
| `category add` | 向知识库添加分类 |
|
||
| `category delete` | 删除知识库中的分类 |
|
||
|
||
### 检索与对话
|
||
|
||
| 命令 | 说明 |
|
||
| :--------- | :------------------------------------ |
|
||
| `search` | 跨知识库语义检索（RAG） |
|
||
| `chat` | 知识库问答（流式输出） |
|
||
| `retrieve` | 查询知识库（已弃用，请使用 `search`） |
|
||
|
||
### 工具命令
|
||
|
||
| 命令 | 说明 |
|
||
| :------------ | :--------------- |
|
||
| `config show` | 显示当前配置 |
|
||
| `config set` | 设置配置项 |
|
||
| `update` | 自更新到最新版本 |
|
||
|
||
> 完整参数说明、输出格式与使用示例请参阅 [CLI 指南](https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md)。
|
||
|
||
## 认证方式
|
||
|
||
推荐使用 DashScope API Key 进行认证。前往 [DashScope 控制台](https://bailian.console.aliyun.com/?tab=app#/api-key) 获取。
|
||
|
||
```bash
|
||
# 方式一：环境变量
|
||
export DASHSCOPE_API_KEY=sk-xxxxx
|
||
|
||
# 方式二：持久化到配置文件（~/.bailian/config.json）
|
||
kscli config set --key api_key --value sk-xxxxx
|
||
|
||
# 方式三：命令行参数
|
||
kscli search --api-key sk-xxxxx --query "..." --agent-id <id> --workspace-id <id>
|
||
```
|
||
|
||
## 配置
|
||
|
||
```bash
|
||
# 查看当前配置
|
||
kscli config show
|
||
|
||
# 设置默认值
|
||
kscli config set --key base_url --value https://dashscope-us.aliyuncs.com
|
||
kscli config set --key timeout --value 600
|
||
|
||
# 设置默认工作区（可免去每次命令传 --workspace-id）
|
||
kscli config set --key workspace_id --value <your-workspace-id>
|
||
|
||
# 自更新
|
||
kscli update
|
||
```
|
||
|
||
配置文件位置：`~/.bailian/config.json`
|
||
|
||
> `--workspace-id` 的解析优先级：命令行参数 > 环境变量 `BAILIAN_WORKSPACE_ID` > 配置文件中的 `workspace_id`。
|
||
|
||
### 全局参数
|
||
|
||
所有命令均支持以下通用参数：
|
||
|
||
| 参数 | 说明 |
|
||
| :---------- | :--------------------------------------- |
|
||
| `--output` | 输出格式：`text`（默认）或 `json` |
|
||
| `--quiet` | 静默模式，仅输出结果值，不显示表头和提示 |
|
||
| `--dry-run` | 预览请求结构，不实际发送到服务端 |
|
||
| `--timeout` | 请求超时时间，单位秒（默认 60） |
|
||
| `--verbose` | 显示详细输出，包括 HTTP 请求详情 |
|
||
| `--config` | 指定自定义配置文件路径 |
|
||
|
||
## 相关链接
|
||
|
||
| 资源 | 地址 |
|
||
| :---------------------- | :-------------------------------------------------------------------------------------------------------- |
|
||
| Knowledge Studio 控制台 | https://rag.console.aliyun.com/ |
|
||
| DashScope API 文档 | https://help.aliyun.com/zh/model-studio/ |
|
||
| 获取 API Key | https://bailian.console.aliyun.com/?tab=app#/api-key |
|
||
| 完整 CLI 指南 | [docs/knowledge-cli-guide.md](https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md) |
|
||
|
||
## 参与贡献
|
||
|
||
欢迎提 Issue、Feature Request 和 PR。开发环境搭建与贡献流程请见 [CONTRIBUTING.zh.md](https://github.com/modelstudioai/cli/blob/main/CONTRIBUTING.zh.md)。
|
||
|
||
## 许可证
|
||
|
||
[Apache 2.0](LICENSE)
|