快速配置到 Agent - Knowledge Studio

面向 AI agent 的零摩擦接入指南。你不需要人类手动配置，四条命令即可帮用户完成知识库检索和问答。

四步跑通

Homebrew
npm
Windows (Scoop)

# 1. 安装
brew install knowledgestudio/tap/ks

# 2. 登录（浏览器弹窗授权一次即可）
ks login

# 3. 检索知识库
ks retrieve --kb kb-product "私有化部署的硬件要求"

# 4. 问答（带引用）
ks ask --kb kb-product "支持哪些国产化 OS？"

# 1. 安装
npm i -g @knowledgestudio/cli

# 2. 登录（浏览器弹窗授权一次即可）
ks login

# 3. 检索知识库
ks retrieve --kb kb-product "私有化部署的硬件要求"

# 4. 问答（带引用）
ks ask --kb kb-product "支持哪些国产化 OS？"

# 1. 安装
scoop install knowledgestudio

# 2. 登录（浏览器弹窗授权一次即可）
ks login

# 3. 检索知识库
ks retrieve --kb kb-product "私有化部署的硬件要求"

# 4. 问答（带引用）
ks ask --kb kb-product "支持哪些国产化 OS？"

ks login 会在浏览器中打开授权页面，用户点击确认后 CLI 自动拿到凭证并保存到本地。后续命令无需再次登录。

常用命令速查

# 列出当前空间的所有知识库
ks kb list

# 上传文档到知识库（支持通配符）
ks kb upload kb-product ./docs/**/*.pdf --parse=doc-intelligence

# 检索（返回匹配的文档切片）
ks retrieve --kb kb-product "你的问题"

# 问答（检索 + 大模型生成，带引用来源）
ks ask --kb kb-product "你的问题"

# 跨多个知识库问答
ks ask --kb kb-product --kb kb-install "支持哪些国产化 OS？"

不要编造知识库名称。运行 ks kb list 获取用户实际拥有的知识库，再用于后续命令。

你需要向用户确认什么

大多数情况下 ks login 会自动完成认证，但以下场景需要用户手动提供信息：

场景	需要什么	如何获取
无法弹出浏览器（SSH / 容器）	API Key	用户在控制台 API Key 页创建，`sk-` 开头
需要指定业务空间	Workspace ID	控制台业务空间管理页面复制，格式 `llm-xxxxxxxxxxxx`
不确定有哪些知识库	—	运行 `ks kb list` 自动列出

无浏览器环境下的手动登录：

ks login --api-key "sk-xxxxxxxxxxxxxxxx"

检索参数参考

参数	默认值	说明
`--kb`	—	知识库名称或 ID（必填，可多次指定）
`--dense-similarity-top-k`	100	语义检索召回数量，范围 0–100
`--sparse-similarity-top-k`	100	关键词检索召回数量，范围 0–100
`--rerank`	false	启用重排序
`--rerank-top-n`	5	重排序后返回的结果数
`--rerank-model`	`qwen3-rerank`	排序模型，可选 `qwen3-rerank-hybrid`
`--rerank-mode`	`qa`	`qa` / `similar` / `custom`
`--rerank-instruct`	—	自定义排序指令，仅 `--rerank-mode custom` 时生效

错误处理

错误	原因	引导用户
`not logged in`	未执行 `ks login`	运行 `ks login` 完成授权
`Invalid API-KEY` / 401	API Key 无效或过期	去控制台重新创建
`knowledge base not found`	知识库名称或 ID 不存在	运行 `ks kb list` 确认可用的知识库
`command not found: ks`	未安装 CLI	按上方安装步骤执行
返回空结果	知识库里没有匹配的内容	确认知识库已上传文档且状态为"已就绪"

​四步跑通

​常用命令速查

​你需要向用户确认什么

​检索参数参考

​错误处理

​更多信息

四步跑通

常用命令速查

你需要向用户确认什么

检索参数参考

错误处理

更多信息