Skip to content

kb.md

Latest commit

 

History

History
370 lines (247 loc) · 12.6 KB

kb.md

File metadata and controls

370 lines (247 loc) · 12.6 KB
Raw

知识库管理命令手册

知识库（Knowledge Base / pipeline / index）是 RAG 的核心载体，存储文档解析后的向量索引。本组命令覆盖知识库的创建、查看、更新、删除和监控。

通用约定（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 总览文档。

bl knowledge list

列出工作区中的知识库。

用法

bl knowledge list [flags]

参数

参数 类型 必填 说明
--name <text> string 否 按知识库名称模糊过滤（1-20 字符）
--page-number <n> number 否 页码（默认：1）
--page-size <n> number 否 每页条数（默认：20，最大 100）

参数约束

  • --name 长度 1-20 字符
  • --page-size 范围 1-100

输出

text 模式：每行一个知识库，字段以双空格分隔，末尾显示总数。

idx-xxx  my-kb  text-embedding-v4  600  product docs
total: 1

quiet 模式：每行一个知识库 ID。

json 模式：返回 API 原始响应，data.rows[] 包含完整知识库信息。

注意事项

  • 返回的 id 字段作为后续命令的 --index-id 使用。

示例

# 列出所有知识库
bl knowledge list --workspace-id ws-xxx

# 按名称过滤，第二页
bl knowledge list --name demo --page-number 2 --page-size 50

bl knowledge info

查看知识库配置详情。

用法

bl knowledge info --index-id <id> [flags]

参数

参数 类型 必填 说明
--index-id <id> string 是 知识库 ID

输出

text 模式：按诊断维度分组展示。

Basic:
  id: idx-xxx
  name: my-kb
  description: product docs
  dataType: ...
Indexing:   [immutable — recreate required to change]
  embeddingModelName: text-embedding-v4
  embeddingDimension: 1024
  chunkSize: 600
  overlapSize: ...
  chunkMode: ...
  separator: ...
Retrieval:
  rerankModelName: ...
  rerankMinScore: ...
  rerankTopN: ...
  rerankMode: ...
  enableRewrite: ...
  denseSimilarityTopK: ...
  sparseSimilarityTopK: ...
Data:
  sourceType: ...
  connectorId: ...

quiet 模式：输出知识库 ID。

json 模式：返回知识库完整配置 JSON。

注意事项

  • 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。

示例

# 查看知识库详情
bl knowledge info --index-id idx-xxx --workspace-id ws-xxx

bl knowledge create

创建知识库并导入数据中心文件或分类。

计费提示：创建成功即开始按运行时长计费，即使不检索也一样。标准版一次性 720 小时额度由多个知识库共享，新用户开通后 30 天内有效；模型调用另计，当前账户剩余额度未核实。见计费规则。可用 --dry-run 预览；直接创建无需 --yes。创建命令的 --help 和创建结果均包含计费提示，JSON 结果通过 notices 提供结构化说明。

用法

bl knowledge create --name <text> --description <text> (--doc-id <id> | --category-id <id>) [flags]

参数

参数 类型 必填 说明
--name <text> string 是 知识库名称（1-20 字符，工作区内唯一）
--description <text> string 是 知识库装了什么内容、给谁用（1-500 字符）
--doc-id <id> array 否¹ 数据中心文件 ID（可重复）；与 --category-id 互斥
--category-id <id> array 否¹ 按分类导入该分类下所有文件（可重复）；与 --doc-id 互斥
--embedding-model <name> string 否 向量模型名称（默认：text-embedding-v4）
--chunk-size <n> number 否 切片大小，字符数（默认：600，建议 300-800）
--wait switch 否 轮询初始导入任务直到终态
--poll-interval <seconds> number 否 轮询间隔秒数（默认：5）

¹ --doc-id 和 --category-id 二选一，必须提供其一。

参数约束

  • --name 长度 1-20 字符
  • --description 长度 1-500 字符，缺失或超长会在本地被拦截
  • --doc-id 和 --category-id 互斥，必须提供其一

输出

text 模式：

index_id: idx-xxx
ingestion_id: job-xxx
status: COMPLETED
Next: check the import job status, then search against this knowledge base.

quiet 模式：stdout 只输出知识库 ID，stderr 仍保留计费提示和已创建资源诊断。

json 模式：保留 API 原始响应，data 包含 pipelineId（知识库 ID）和 ingestionId（导入任务 ID），并追加：

  • notices：计费提示，包含 code: "KNOWLEDGE_BILLING"、本地化 message、计费规则 url 和 remainingAllowance: "unknown"。不代表已查询账户余额。
  • resources：本次创建的资源及清理指令。
  • final_status：仅在使用 --wait 并获得导入终态时返回。

提示不会在 JSON stdout 后追加普通文本；stderr 单独输出诊断信息。text 模式的上述示例仅展示 stdout，计费提示同时显示在 stderr。

注意事项

  • 结构/存储类型固定为默认文档知识库（非结构化，BUILT_IN 存储）。
  • 返回知识库 ID（pipelineId）和初始导入任务 ID（ingestionId）。
  • 使用 doc status 或 --wait 跟踪导入进度。
  • 创建响应返回后立即向 stderr 报告知识库 ID、工作空间与持续计费提醒，quiet 模式也保留；JSON 结果保留 API 响应并追加资源和提醒信息。
  • 当前产品注册了删除命令时，资源中的 cleanup.command 给出真实 bin、path 和 args；text 模式显示可复制的指令。指令不自动添加 --yes，不存在唯一删除路径时不猜测路径。
  • 如果后续等待失败，命令返回非零退出码，知识库仍可能已创建并持续计费。根据已输出 ID 核对资源，不要盲目重复创建。确认不再需要后，使用 bl knowledge delete --index-id <index-id> --workspace-id <workspace-id>（kscli 对应 kb delete）清理；确认删除范围后才添加 --yes。仅删除文档或检索服务不能停止知识库规格计费。

示例

# 查看建库帮助中的计费提示
bl knowledge create --help
# kscli 对应：kscli kb create --help

# 从指定文件创建知识库，无需 --yes
bl knowledge create --name demo --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx

# 从分类导入并等待导入完成
bl knowledge create --name demo --description '产品文档' --category-id cate-xxx --wait

# 指定向量模型和切片大小
bl knowledge create --name my-kb --description '产品文档 v2' --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx

bl knowledge update

更新知识库名称、描述或 rerank 阈值。

用法

bl knowledge update --index-id <id> [flags]

参数

参数 类型 必填 说明
--index-id <id> string 是 知识库 ID
--name <text> string 否 新名称（1-20 字符）
--description <text> string 否 新描述
--rerank-min-score <score> number 否 rerank 最低分数阈值，范围 0-1（低于此分的 chunk 被过滤）

参数约束

  • 至少提供 --name、--description、--rerank-min-score 之一，否则报错 "Nothing to update"
  • --name 长度 1-20 字符
  • --rerank-min-score 范围 0-1

输出

text 模式：

updated: idx-xxx

quiet 模式：无输出。

json 模式：返回 API 原始响应。

注意事项

  • 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。

示例

# 更新描述
bl knowledge update --index-id idx-xxx --description "product docs v2" --workspace-id ws-xxx

# 调整 rerank 阈值
bl knowledge update --index-id idx-xxx --rerank-min-score 0.3

bl knowledge delete

删除知识库及其所有文档和 chunk。

用法

bl knowledge delete --index-id <id> [flags]

参数

参数 类型 必填 说明
--index-id <id> string 是 知识库 ID
--yes switch 否 显式确认执行高风险操作

输出

text 模式：

deleted: idx-xxx

quiet 模式：无输出。

json 模式：返回 API 原始响应。

注意事项

  • 不可逆操作：知识库及所有索引内容被永久删除。
  • 数据中心中的源文件不受影响，仅删除知识库索引。
  • 不带 --yes 时，runtime 会在调用知识库业务 API、执行删除前返回确认请求。

示例

# 删除（交互确认）
bl knowledge delete --index-id idx-xxx --workspace-id ws-xxx

# 跳过确认
bl knowledge delete --index-id idx-xxx --yes

bl knowledge stats

查看知识库存储和 QPS 监控数据。

用法

bl knowledge stats --index-id <id> [flags]

参数

参数 类型 必填 说明
--index-id <id> string 是 知识库 ID
--start <time> string 否 范围起始：Unix 秒或 ISO 日期（默认：24 小时前）
--end <time> string 否 范围结束：Unix 秒或 ISO 日期（默认：当前时间）

输出

text 模式：

plan: ...
storage: 100 / 1000
peak qps: 5
qps windows: 24 data point(s)

quiet 模式：输出 json 格式。

json 模式：返回 API 原始响应，包含 storageMonitorData 和 qpsMonitorData。

注意事项

  • 默认查询最近 24 小时数据。
  • 时间戳自动转换为 epoch 秒（API 要求秒级字符串）。13 位毫秒时间戳会自动降为秒。

示例

# 查看最近 24 小时监控
bl knowledge stats --index-id idx-xxx --workspace-id ws-xxx

# 指定日期范围
bl knowledge stats --index-id idx-xxx --start 2026-07-30 --end 2026-07-31

← 返回总览

音视频知识库

create 新增 --knowledge-type document|multimedia、--knowledge-scene 和 --multimodal-embedding-model。音视频类型固定使用 basic_multimedia_qa；未传 scene 时自动填充，显式冲突时本地拒绝。

bl knowledge create --name media-demo --description "音视频资料" --doc-id file-example --knowledge-type multimedia

音视频请求默认发送 embeddingModelName=qwen3-vl-embedding、rerankModelName=qwen3-vl-rerank、rerankMode=similar，与管控台切换逻辑及现有音视频库的只读配置一致。音视频场景的 --multimodal-embedding-model 是 --embedding-model 的别名，两者互斥，均映射到 embeddingModelName，不能误用图片建库的 multimodalEmbeddingModelName。视觉理解文档场景 visual_perception_qa 同样使用 VL embedding，但不默认加入 rerank。

普通文档未使用新参数时仍为 text-embedding-v4。显式模型仍由服务端校验其允许列表；CLI 不把当前观察到的模型名称硬编码成永久白名单。只读核对不代表已新建媒体库进行解析验收。

list 文本增加类型，info 文本展示 knowledgeType、knowledgeScene、multimodalEmbeddingModelName。JSON 保留服务端对象及未知字段。列表接口缺少这三个字段按后端 bug 处理；null/缺失不代表普通文档库，CLI 不发额外探测请求、不推断或写回，也不提供 multimediaVersion 参数。