五种接入方式怎么选
把「谁来生成最终回答」和「是否需要编排平台资源」拆开看,选型一目了然:
| 接入方式 | 协议与入口 | 适用场景 | 推荐鉴权 | 延伸指南 |
|---|---|---|---|---|
| 声明式配置 API | /api/v2/workspaces/{id}/agents/knowledge-bases/config/connections |
用 IaC / CI / 后台程序创建、局部修改、预演与同步 Agent、知识库和外部连接 | 组织 API Key 或 OAuth | 声明式配置 |
| 原生 Turn 对话 API | /api/v2/bots/{id}/chats/api/v2/agent/chats/{id}/turns |
保留多轮上下文、获取结构化 parts[]、句级引用证据、工具确认与 PDF 导出 |
API Key / Agent API Key / OAuth | 对话与异步 Turn |
| OpenAI 兼容接口 | POST /v1/chat/completions |
复用现有 OpenAI SDK、LangChain 或 Chat UI,零改造切换为 ApeMind Agent 回答 | API Key | OpenAI 兼容接口 |
| MCP Server | POST /mcp/(Streamable HTTP) |
让 Cursor、Claude Code 或自研 Agent 直接检索 ApeMind 知识库、图谱与外部连接,由你的 Agent 生成回答 | API Key 或 OAuth | MCP 接入与工具参考 |
| A2A 1.0 协议 | /v1/a2a/bots/{id}(JSON-RPC + SSE) |
多智能体编排框架通过标准 Agent Card 发现并异步调度 ApeMind Agent | 组织 API Key | A2A 1.0 协议接入 |
实时同步的全部 REST 路径、字段类型、枚举值与在线调试都在 API 参考(对应部署的 /api/openapi.json)。本栏目的每一篇只覆盖跨接口状态机、权限边界、非显而易见的运行约束以及 OpenAPI 未覆盖的协议(/mcp/、A2A、CLI 评测闭环)。
环境与入口约定
SaaS 与私有化部署共享同一套 API 契约,只需替换根域名:
| 资源 | SaaS 正式环境 | 私有化部署 |
|---|---|---|
| API 根地址 | https://apemind.ai |
https://<APEMIND_HOST> |
| MCP Server | https://apemind.ai/mcp/ |
https://<APEMIND_HOST>/mcp/ |
| OpenAI 兼容根地址 | https://apemind.ai/v1 |
https://<APEMIND_HOST>/v1 |
| OpenAPI 规范 | https://apemind.ai/api/openapi.json |
https://<APEMIND_HOST>/api/openapi.json |
本文及本栏目示例统一使用以下环境变量:
export APEMIND_BASE_URL="https://apemind.ai"
export APEMIND_ORG_ID="<ORGANIZATION_ID>"
export APEMIND_API_KEY="<API_KEY>"
十分钟最小集成闭环
下面以「准备一个可问答的 Agent 并获取带证据的回答」为例,串起最典型的服务端接入步骤:
-
签发凭据并确认组织 ID
在目标组织的设置页创建组织服务账号并签发 API Key,或在个人设置中为该组织创建 API Key。验证凭据和当前身份:
curl --fail-with-body \ -H "Authorization: Bearer ${APEMIND_API_KEY}" \ "${APEMIND_BASE_URL}/api/v2/auth/user" -
声明式创建知识库并上传文档
推荐通过声明式配置接口创建知识库(先加
?dry_run=true预演),随后上传文件并等待索引就绪。完整状态机见知识库入库与检索编排。curl --fail-with-body \ -X POST "${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/knowledge-bases/config" \ -H "Authorization: Bearer ${APEMIND_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "metadata": {"title": "产品文档库"}, "spec": {"enable_vector": true, "enable_fulltext": true} }' -
声明式创建 Agent 并挂载知识库
通过
POST /api/v2/workspaces/{org_id}/agents一次写清模型、人设与知识库权限(spec.model: "default"自动使用组织默认对话模型):curl --fail-with-body \ -X POST "${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/agents" \ -H "Authorization: Bearer ${APEMIND_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "metadata": {"title": "产品顾问"}, "spec": { "model": "default", "instructions": "基于知识库准确回答产品问题并给出出处。", "capabilities": { "knowledge": { "scope": "listed", "bases": {"<KB_ID>": {"default": true}}, "level": "view" } } } }' -
发起提问并读取回答
需要快速接入已有 SDK 时直接调 OpenAI 兼容端点;需要完整工具轨迹、交互确认与结构化引用时走原生 Turn API(详见对话与异步 Turn 集成):
curl --fail-with-body \ -X POST "${APEMIND_BASE_URL}/v1/chat/completions?bot_id=<AGENT_ID>&language=zh-CN" \ -H "Authorization: Bearer ${APEMIND_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "model": "apemind", "messages": [{"role": "user", "content": "退换货时限是几天?"}] }'
关于 CLI 与历史路径命名
- 命令行工具
apemind:日常调试、声明式配置 diff/apply 与自动化评测优先使用官方 CLI(tools/apemind-cli),免去手写分页与轮询逻辑;完整评测闭环见问答集评测与 CLI 调优闭环。 - 历史路径兼容:新接口统一使用
/agents、/knowledge-bases和/connections;部分历史路径(如对话入口/api/v2/bots/{bot_id}/chats、检索入口/api/v2/collections/{collection_id}/searches)保留原路径命名以保持兼容,文档中对应的业务概念一律称为 Agent 和 知识库。 - 已废弃写接口:
POST/PUT /api/v2/bots与POST/PUT /api/v2/collections已在 OpenAPI 中标记废弃,新集成请统一使用声明式配置接口。