服务渠道 - Knowledge Studio

知识检索和问答服务发布后，可以通过多种渠道接入到你的应用中。在控制台 应用集成 → 服务渠道 页面，可以查看各渠道的接入信息和示例代码。

接入方式对比

渠道	类型	适用场景	说明
REST API	REST / SSE	自有后端服务	DashScope HTTP 接口，配套多语言 SDK（Python / Java）
MCP Server	MCP 协议	AI Agent 框架	支持 Qoder / Claude Code / Codex 等客户端
CLI	命令行	本地调试 / 脚本 / CI	`kscli`，34 个命令覆盖知识库管理与检索问答
Agent Skill	技能包	Qoder / Claude Code	以技能包形式接入，AI 编码工具自动加载
百炼 Agent	Web	快速验证 / 低代码	阿里云百炼智能体应用，支持 Agent 绑定和 Workflow 绑定

REST API

所有检索与问答能力通过 DashScope API 提供，服务地址为 https://{workspaceId}.cn-beijing.maas.aliyuncs.com。 鉴权方式：

Authorization: Bearer <API-Key>

API Key 在控制台 API Key 页创建，系统根据 API Key 自动路由到对应业务空间。 主要接口：

接口	方法	路径	说明
知识搜索	POST	`/api/v1/indices/knowledge/search`	应用级联合检索，由知识检索服务配置驱动，调用方仅需传入 `query` 和 `agent_id`
知识问答	POST	`/api/v2/apps/knowledge/chat`	流式问答，返回 SSE 事件
底层检索	POST	`/api/v1/indices/rag/index/retrieve`	单知识库底层检索，直接返回向量 + 关键词召回结果，不在此层做重排

知识搜索接口示例（控制台服务渠道页面提供的示例）：

curl -X POST 'https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $DASHSCOPE_API_KEY' \
  -d '{
    "query": "${YOUR_QUERY}",
    "agent_id": "${YOUR_APP_ID}"
  }'

检索范围和策略（多库权重、路由、混排等）由 agent_id 对应的知识检索服务配置驱动，调用方无需在请求中重复传入检索参数。 底层检索接口示例（直接指定知识库 ID）：

curl -X POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/index/retrieve \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index_id": "<知识库ID>",
    "query": "如何配置切片策略？",
    "top_k": 5
  }'

单知识库底层检索接口直接返回向量 + 关键词召回结果，不在此层做重排。如需 Rerank 精排，在创建检索服务时配置混排模型，通过知识搜索接口（agent_id）调用。

完整接口列表见 API 参考。

MCP Server

MCP（Model Context Protocol）是一种开放协议，让 AI 编码助手和 Agent 框架直接调用外部工具。接入 RAG MCP Server 后，你的 AI 助手可以在对话中检索知识库内容。

前置条件

已创建至少一个知识库，且包含已解析完成的文档
已获取 API Key
已安装支持 MCP 协议的客户端（Qoder、Claude Code、Codex 等）

接入步骤

获取 API Key

在控制台 API Key 页创建 API Key。建议将 API Key 存为环境变量：

export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxx"

在客户端中添加 MCP Server

根据你使用的客户端，选择对应的配置方式：

Qoder / QoderWork
Claude Code
Codex

打开 MCP 配置文件，添加以下内容：

{
  "mcpServers": {
    "rag_mcp": {
      "type": "streamableHttp",
      "url": "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp",
      "headers": {
        "Authorization": "Bearer ${DASHSCOPE_API_KEY}"
      }
    }
  }
}

在终端中执行：

claude mcp add --transport http rag-mcp-server \
  https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp \
  --header "Authorization: Bearer ${DASHSCOPE_API_KEY}"

在 Codex 配置文件中添加：

[mcp_servers.rag_mcp_server]
url = "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp"
http_headers = {
    "Authorization" = "Bearer ${DASHSCOPE_API_KEY}"
}

Codex 0.120.0 及以上版本支持。

验证连接

配置完成后，在客户端中尝试调用知识库。例如在 Claude Code 中输入：

帮我在知识库里搜索"如何创建知识库"

如果 AI 助手成功调用了 Retrieve 工具并返回检索结果，说明接入成功。

连接信息

项	值
端点	`https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp`
协议版本	MCP 2024-11-05
传输方式	Streamable HTTP（POST + GET SSE）
鉴权	`Authorization: Bearer <API-Key>`

提供的工具（Tools）

工具名	功能	说明
`Retrieve`	检索知识库	从指定知识库检索相关切片，支持混合检索和 Rerank
`ListIndices`	查询知识库列表	分页获取当前业务空间下的知识库列表

Retrieve 的参数：

参数	类型	必填	默认值	说明
`IndexId`	string	是	—	知识库索引 ID
`Query`	string	是	—	查询文本，不能为空
`DenseSimilarityTopK`	integer	否	100	语义检索召回数量，范围 0–100
`SparseSimilarityTopK`	integer	否	100	关键词检索召回数量，范围 0–100
`EnableReranking`	boolean	否	true	是否启用重排序
`Rerank.ModelName`	string	否	qwen3-rerank	排序模型，可选 `qwen3-rerank` 或 `qwen3-rerank-hybrid`

DenseSimilarityTopK 与 SparseSimilarityTopK 之和必须不小于 RerankTopN（默认 5），否则返回 Index.InvalidParameter，报错信息为 dense_similarity_top_k + sparse_similarity_top_k >= rerank_top_n。例如默认 RerankTopN 下 Dense=1、Sparse=0 会报错，而 Dense=3、Sparse=2 可正常检索。

Rerank 对象中的 RerankMode、RerankMinScore、RerankTopN、RerankInstruct 参数当前版本暂不可用，传入会返回错误。如需控制重排序行为，使用 EnableReranking 和 Rerank.ModelName 即可。

ListIndices 的参数：

参数	类型	必填	默认值	说明
`pageNumber`	integer	否	1	页码，从 1 开始
`pageSize`	integer	否	10	每页数量
`indexName`	string	否	—	按知识库名称前缀过滤

支持的客户端：

Qoder / QoderWork
Claude Code
Codex（0.120.0+）
其他支持 MCP 协议的客户端

CLI

kscli（Knowledge Studio CLI）是知识库的命令行工具，覆盖知识库搭建、内容运维、检索服务管理和检索问答全流程，共 34 个命令。无需编写代码即可完成知识库管理，适合本地调试、脚本集成和 CI/CD 流程。控制台 服务渠道 页面提供安装命令和使用示例。

前置条件

已安装 Node.js（20 及以上版本）
已创建至少一个知识库，且包含已解析完成的文档
已获取 API Key

上手步骤

安装 CLI

npm install -g knowledge-studio-cli

执行 kscli --version 验证安装。

配置 API Key 与业务空间

写入配置文件后，后续命令无需重复指定：

kscli config set --key api_key --value sk-xxxxxxxxxxxxxxxx
kscli config set --key workspace_id --value ws-xxxxxxxx

运行第一次检索

先查看业务空间中的检索服务，再用服务 ID 执行检索：

kscli service list --scene search
kscli search --query "你的问题" --agent-id aid-xxxxxxxx

命令会输出检索到的文档切片及相关性分数。

常用命令

命令	功能
`kscli kb list`	列出知识库
`kscli doc upload --file <path> --index-id <id>`	上传文件并导入知识库
`kscli service list --scene search`	查看检索服务及其 ID
`kscli search --query <text> --agent-id <id>`	执行语义检索
`kscli chat --message <text> --agent-id <id>`	进行 RAG 对话

kscli retrieve --index-id 是早期的直连检索命令，目前已废弃，执行时会输出废弃警告。请改用 search：检索范围与策略由 --agent-id 对应的服务配置驱动，支持多知识库、路由和重排。

完整的 34 个命令、参数约束与输出说明见 CLI 命令参考。

Agent Skill

在 Qoder / Claude Code 等 AI 编码工具中，把知识库作为技能包接入。安装地址为 https://skills.aliyun.com/skills/alibabacloud-bailian-rag-knowledgebase，可在控制台 服务渠道 → Agent Skill 页面获取。安装后 AI 编码工具自动识别并加载知识库检索能力，无需手动编写配置。

百炼 Agent

KnowledgeStudio 知识库可作为外部能力接入阿里云百炼智能体应用，支持两种绑定方式：

方式一：Agent 绑定（推荐）

适用于新版智能体应用（Agent 2.0）。知识库作为智能体的一项技能，由智能体自主规划何时调用，与 MCP 等其他工具统一调度。

在百炼控制台创建应用 → 智能体应用 → Agent 2.0
在「知识库」区域选择「外部知识库 → KnowledgeStudio」
粘贴 API Key 与知识库 ID，发布后即可调用

方式二：Workflow 绑定

适用于百炼工作流应用。将复杂任务拆分为有序节点（大模型节点、意图分类、结束节点等），KnowledgeStudio 可作为「知识库检索节点」被工作流调用。

在百炼控制台创建应用 → 工作流应用
在画布拖入「知识库检索」节点，选择「KnowledgeStudio」作为检索源
连接开始节点 / 大模型节点 / 结束节点，发布为应用

选型建议

方式	适用场景
Agent 绑定	任务不固定、需多步推理、需要智能体自主决策。例如企业智能问答、复杂研究任务
Workflow 绑定	流程固定、需严格控制执行顺序。例如报告生成、客服分流、诊断辅助

如果你的应用使用 Dify / Coze 等第三方平台构建，参考第三方接入获取详细的配置指南。

​接入方式对比

​REST API

​MCP Server

​前置条件

​接入步骤

​连接信息

​提供的工具（Tools）

​CLI

​前置条件

​上手步骤

​常用命令

​Agent Skill

​百炼 Agent

​方式一：Agent 绑定（推荐）

​方式二：Workflow 绑定

​选型建议

接入方式对比

REST API

MCP Server

前置条件

接入步骤

连接信息

提供的工具（Tools）

CLI

前置条件

上手步骤

常用命令

Agent Skill

百炼 Agent

方式一：Agent 绑定（推荐）

方式二：Workflow 绑定

选型建议