Agent Storage 命令行工具知识库操作 - 表格存储

本文档介绍命令行工具中知识库（Knowledge Base）相关的命令及参数，覆盖知识库管理、文档管理、文档检索和子空间工作流。

前置条件

已完成命令行工具的安装与访问凭证配置。具体操作，请参见命令行工具。
如需上传文档，需提前配置 OSS Bucket（oss_endpoint 和 oss_bucket_name），或交由命令行工具自动创建托管 Bucket。

知识库管理

知识库是文档存储和语义检索的顶层容器。

创建知识库

tablestore-agent-cli kb create --name my_kb --description "产品文档知识库"

支持启用子空间和自定义 Embedding 模型等更多选项：

tablestore-agent-cli kb create --name product_docs \
  --description "产品文档" \
  --tags "tech,docs" \
  --subspace \
  --embedding-provider bailian \
  --embedding-model text-embedding-v4 \
  --embedding-dimension 1024

参数说明：

参数	必填	默认值	说明
`--name`	是	—	知识库名称。字母、数字、下划线，字母开头，长度 1~64 字符。
`--description`	否	—	描述信息。不超过 4 KB。
`--subspace`	否	`false`	是否启用子空间分区。
`--tags`	否	—	标签。逗号分隔，总大小不超过 4 KB。
`--metadata`	否	—	Metadata schema 的 JSON 字符串。与 `--metadata-file` 互斥。
`--metadata-file`	否	—	Metadata schema 的 JSON 文件路径。
`--config-file`	否	—	完整请求体 JSON 文件路径。与其他参数互斥。
`--embedding-provider`	否	—	Embedding 服务提供方。可选值为 `bailian` 或 `custom`。
`--embedding-model`	否	—	Embedding 模型名称。如 `text-embedding-v4`。
`--embedding-dimension`	否	—	向量维度。
`--embedding-api-key`	否	—	自定义 Embedding 服务的 API Key。
`--embedding-url`	否	—	自定义 Embedding 服务的 URL。需提前在 OTS 注册。
`--retrieval-config-file`	否	—	检索配置的 JSON 文件路径。

Metadata 字段类型：支持 string、long、double、boolean、date 及对应的 list 变体。单个知识库最多支持 200 个 Metadata 字段，字段名称不超过 128 字符。

列出知识库

tablestore-agent-cli kb list
tablestore-agent-cli kb list --limit 50

kb list 自动翻页，返回当前账号下的全部知识库。--limit 指定每页返回数量，不影响最终结果总数。

查看知识库

tablestore-agent-cli kb describe --name my_kb

输出包含知识库的基本元信息、Embedding 配置和检索配置。

删除知识库

重要

删除知识库会清除其下全部文档和向量数据，且不可恢复。请谨慎操作。

tablestore-agent-cli kb delete --name my_kb        # TTY 环境下会提示确认
tablestore-agent-cli kb delete --name my_kb -y     # 跳过确认

文档管理

添加文档

支持三种来源：本地文件、本地目录、已有 OSS 对象。

添加本地文件：

tablestore-agent-cli kb doc-add --kb my_kb --file ./report.pdf
tablestore-agent-cli kb doc-add --kb my_kb --file ./doc1.pdf --file ./doc2.md

扫描本地目录（支持递归和 glob 过滤）：

说明

支持首尾 * 通配符（如*.pdf）。

tablestore-agent-cli kb doc-add --kb my_kb --dir ./docs
tablestore-agent-cli kb doc-add --kb my_kb --dir ./docs --include "*.pdf,*.md"
tablestore-agent-cli kb doc-add --kb my_kb --dir ./docs --exclude "*.tmp" --no-recursive

添加已有 OSS 对象：

tablestore-agent-cli kb doc-add --kb my_kb --oss-key oss://my-bucket/data.pdf

指定子空间和元数据：

tablestore-agent-cli kb doc-add --kb my_kb --file ./doc.pdf --subspace tenant_A --metadata '{"author":"Alice"}'

参数说明：

参数	必填	默认值	说明
`--kb`	是	—	知识库名称。
`--file` / `--dir` / `--oss-key`	三选一	—	文档来源。支持重复指定以批量上传。
`--subspace`	KB 启用子空间时必填	—	子空间名称。
`--metadata`	否	—	Metadata JSON 字符串。与 `--metadata-file` 互斥。
`--metadata-file`	否	—	Metadata JSON 文件路径。
`--include`	否	—	glob 模式白名单。逗号分隔。
`--exclude`	否	—	glob 模式黑名单。逗号分隔。
`--recursive`	否	`true`	是否递归扫描子目录。`--no-recursive` 仅扫描顶层。
`--concurrency`	否	`4`	上传并发数。

支持的文件格式：PDF、DOCX、DOC、WPS、PPTX、PPT、TXT、Markdown、HTML、XLSX、XLS、PNG、JPG、BMP、GIF。

查看文档

tablestore-agent-cli kb doc-get --kb my_kb --doc-id doc-123
tablestore-agent-cli kb doc-get --kb my_kb --oss-key data.pdf

输出包含文档状态（pending、completed 或 failed）、分块数量、元数据等信息。

列出文档

tablestore-agent-cli kb doc-list --kb my_kb
tablestore-agent-cli kb doc-list --kb my_kb --subspace tenant_A,tenant_B

自动翻页，返回知识库下的全部文档。--subspace 支持指定多个子空间，使用逗号分隔。

移除文档

tablestore-agent-cli kb doc-remove --kb my_kb --doc-id doc-123
tablestore-agent-cli kb doc-remove --kb my_kb --oss-key data.pdf --delete-file

--delete-file 用于同时删除 OSS 中的源文件。未指定时仅从知识库中移除索引，OSS 源文件保留。

文档检索

针对知识库执行向量检索、全文检索或两者的混合检索。

基础检索

tablestore-agent-cli kb retrieve --kb my_kb --query "系统架构设计"

常用场景

指定检索类型和返回数量：

tablestore-agent-cli kb retrieve --kb my_kb --query "SSL证书" --search-type DENSE_VECTOR --top-k 5

通过 Metadata 过滤：

tablestore-agent-cli kb retrieve --kb my_kb --query "部署指南" --filter '{"author":{"equals":"Alice"}}'

多子空间检索：

tablestore-agent-cli kb retrieve --kb my_kb --query "policy" --subspace "tenant_A,tenant_B"

指定重排策略：

tablestore-agent-cli kb retrieve --kb my_kb --query "优化方案" --rerank-type WEIGHT --weight-dense 0.7 --weight-fulltext 0.3

参数说明

参数	默认值	说明
`--search-type`	`DENSE_VECTOR,FULL_TEXT`	检索类型。可选值为 `DENSE_VECTOR`、`FULL_TEXT`。多个值使用逗号分隔。
`--top-k`	`20`	同时设置 dense、fulltext 和重排阶段的返回数量。
`--rerank-type`	—	重排策略。可选值为 `RRF`、`WEIGHT`、`MODEL`。
`--rrf-k` / `--rrf-dense-weight` / `--rrf-fulltext-weight`	—	RRF 重排参数。
`--weight-dense` / `--weight-fulltext`	—	WEIGHT 重排时 dense 和 fulltext 的权重。
`--model-provider` / `--model-name`	—	MODEL 重排时的模型提供方与模型名称。如 `bailian` 和 `gte-rerank-v2`。
`--filter`	—	Metadata 过滤 JSON 字符串。与 `--filter-file` 互斥。
`--filter-file`	—	Metadata 过滤 JSON 文件路径。
`--subspace`	—	子空间列表。逗号分隔。

Metadata 过滤运算符

运算符	示例
`equals` / `notEquals`	`{"author":{"equals":"Alice"}}`
`greaterThan` / `lessThan`	`{"score":{"greaterThan":80}}`
`in` / `notIn`	`{"author":{"in":["Alice","Bob"]}}`
`startsWith` / `stringContains`	`{"name":{"startsWith":"ssl"}}`
`listContains`	`{"tags":{"listContains":"tech"}}`
`andAll` / `orAll` / `notAll`	`{"andAll":[{...},{...}]}`

子空间工作流

子空间用于在同一知识库中隔离多租户、多业务线或多场景的数据。创建知识库时通过 --subspace 开启子空间分区，后续的文档上传和检索操作均需指定子空间。

# 创建启用子空间的知识库
tablestore-agent-cli kb create --name multi_tenant_kb --subspace

# 上传时指定子空间
tablestore-agent-cli kb doc-add --kb multi_tenant_kb --file ./doc.pdf --subspace tenant_A

# 检索时支持指定多个子空间
tablestore-agent-cli kb retrieve --kb multi_tenant_kb --query "policy" --subspace "tenant_A,tenant_B"

适用场景：多租户隔离、按业务线归档、A/B 测试等。