服务渠道 - 千问AI平台

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

接入方式对比

渠道	类型	适用场景	说明
REST API	REST / SSE	自有后端服务	DashScope HTTP 接口，配套多语言 SDK（Python / Java）
MCP Server	MCP 协议	AI Agent 框架	支持 Qoder / Claude Code / Codex 等客户端
Agent Skill	技能包	Qoder / Claude Code	以技能包形式接入，AI 编码工具自动加载

REST API

所有检索与问答能力通过 DashScope API 提供，服务地址为 https://dashscope.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://dashscope.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://dashscope.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://dashscope.aliyuncs.com/api/v1/indices/rag/mcp",
      "headers": {
        "Authorization": "Bearer ${DASHSCOPE_API_KEY}"
      }
    }
  }
}

在 Codex 配置文件中添加：

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

Codex 0.120.0 及以上版本支持。

验证连接

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

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

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

连接信息

项	值
端点	`https://dashscope.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 之和必须大于 1，不支持只用其中一种方式检索（例如 Dense=1, Sparse=0 会报错）。

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 协议的客户端

Agent Skill

在 Qoder / Claude Code 等 AI 编码工具中，把知识库作为技能包接入。技能详情页为知识库（RAG）技能。这条路走的是主站技能市场，控制台的服务渠道页面只有 REST API 和 MCP Server 两个渠道，没有 Agent Skill。在详情页安装方式的让 Agent 装标签点复制提示词，把提示词贴给你的 Agent，由它完成安装；也可以切到我自己装标签，用 qianwen skills install 装或者直接下载 ZIP。安装后 AI 编码工具即可识别并加载知识库检索能力，无需手动编写配置。

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

​接入方式对比

​REST API

​MCP Server

​前置条件

​接入步骤

​连接信息

​提供的工具（Tools）

​Agent Skill

接入方式对比

REST API

MCP Server

前置条件

接入步骤

连接信息

提供的工具（Tools）

Agent Skill