后端API集成指南
原创
灵阙教研团队
S 精选 入门 参考手册 |
约 7 分钟阅读
更新于 2025-12-23 AI 导读
后端API集成指南 概述 本文档说明如何使用已实现的后端API端点，这些端点为MCP和Skill系统提供真实的执行能力。 已集成的LLM提供商 1. Anthropic Claude 模型：claude-3-5-sonnet-20241022, claude-3-opus, claude-3-haiku 用途：高质量推理、代码生成、长文本处理 API Key: 已配置 2. OpenAI GPT...
后端API集成指南
概述
本文档说明如何使用已实现的后端API端点，这些端点为MCP和Skill系统提供真实的执行能力。
已集成的LLM提供商
1. Anthropic Claude ✅
- 模型：claude-3-5-sonnet-20241022, claude-3-opus, claude-3-haiku
- 用途：高质量推理、代码生成、长文本处理
- API Key: 已配置
2. OpenAI GPT ✅
- 模型：gpt-4o, gpt-4o-mini, gpt-3.5-turbo
- 用途：通用对话、代码辅助
- API Key: 已配置
3. OpenRouter ✅
- 提供商：多模型聚合路由
- 用途：访问多种开源和闭源模型
- API Key: 已配置
4. SiliconFlow ✅
- 模型：Qwen2-7B, DeepSeek等
- 用途：中文优化模型
- API Key: 已配置
5. Kimi (Moonshot) ✅
- 模型：moonshot-v1-8k, moonshot-v1-32k
- 用途：长上下文中文处理
- API Key: 已配置
6. Zhipu BigModel (智谱) ✅
- 模型：glm-4, glm-4-plus
- 用途：中文大模型
- API Key: 已配置
7. Poe ✅
- 提供商：多模型聚合
- API Key: 已配置
8. Google AI Studio ✅
- 模型：Gemini系列
- API Key: 已配置
9. ElevenLabs ✅
- 用途：TTS音频生成
- API Key: 已配置
MCP API端点
1. 连接MCP服务器
端点: POST /api/mcp/servers/:serverId/connect
请求体:
{
"config": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
"env": {
"NODE_ENV": "production"
}
}
}
响应:
{
"success": true,
"connectedAt": "2025-01-10T10:30:00.000Z"
}
使用示例:
const mcpManager = getMCPManager();
await mcpManager.addServer({
id: 'filesystem',
name: 'Filesystem Tools',
type: 'stdio',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
});
2. 获取工具列表
端点: GET /api/mcp/servers/:serverId/tools
响应:
{
"tools": [
{
"name": "read_file",
"description": "Read a file from the filesystem",
"inputSchema": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Path to the file"
}
},
"required": ["path"]
},
"serverId": "filesystem"
}
]
}
3. 调用MCP工具
端点: POST /api/mcp/servers/:serverId/call-tool
请求体:
{
"name": "read_file",
"arguments": {
"path": "/tmp/test.txt"
}
}
响应:
{
"success": true,
"content": [
{
"type": "text",
"text": "File contents here..."
}
]
}
Skill API端点
执行Skill
端点: POST /api/skills/execute
请求体:
{
"skillId": "data-analyst",
"inputs": {
"data": "name,age,salary\nJohn,30,50000\n...",
"analysisType": "summary"
},
"instructions": "You are an expert data analyst. Analyze the provided data and generate insights.",
"options": {
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022",
"temperature": 0.7,
"maxTokens": 4096
}
}
响应:
{
"success": true,
"outputs": {
"result": "Data analysis results..."
},
"duration": 2500,
"metadata": {
"tokensUsed": 1523,
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022"
}
}
完整使用示例
示例1: 使用MCP文件系统工具
// 1. 初始化MCP系统
import { initializeMCPManager, mcpPluginAdapter } from '@/lib/mcp';
import { initializePluginManager } from '@/lib/plugin-system';
const mcpManager = initializeMCPManager({
apiBaseUrl: '/api/mcp',
autoConnect: true,
});
// 2. 添加文件系统服务器
await mcpManager.addServer({
id: 'filesystem',
name: 'Filesystem',
type: 'stdio',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace'],
});
// 3. 加载MCP适配器（自动将工具转换为节点）
const pluginManager = initializePluginManager();
await pluginManager.loadPlugin(mcpPluginAdapter);
// 4. 在工作流中使用（工具已自动注册为节点）
const workflow = {
nodes: [
{
id: 'read-file',
type: 'mcp_filesystem_read_file', // 自动注册的节点类型
data: {
label: '读取文件',
config: {
toolName: 'read_file',
},
},
},
],
};
const executor = new WorkflowExecutor(workflow, {}, {
userId: 'user-123',
workspaceId: 'ws-456',
tenantId: 'tenant-789',
});
const result = await executor.execute({
path: '/workspace/data.txt',
});
console.log(result.outputs); // 文件内容
示例2: 使用Skill进行数据分析
// 1. 初始化Skill系统
import { initializeSkillManager, skillPluginAdapter } from '@/lib/skill';
const skillManager = initializeSkillManager({
apiBaseUrl: '/api/skills',
autoEnable: true,
});
// 2. 注册自定义Skill加载器
class CustomSkillLoader implements SkillLoader {
async load(config: SkillConfig): Promise<SkillDefinition> {
return {
config,
inputs: [
{ name: 'data', type: 'string', required: true, description: 'CSV数据' },
{ name: 'analysisType', type: 'string', description: '分析类型' },
],
outputs: [
{ name: 'result', type: 'string', description: '分析结果' },
],
instructions: 'You are an expert data analyst...',
supportsStreaming: false,
};
}
async validate(definition: SkillDefinition) {
return { valid: true };
}
}
skillManager.registerLoader('custom', new CustomSkillLoader());
// 3. 注册Skill
await skillManager.registerSkill({
id: 'data-analyst',
name: 'Data Analyst',
source: 'custom',
});
// 4. 加载Skill适配器
const pluginManager = initializePluginManager();
await pluginManager.loadPlugin(skillPluginAdapter);
// 5. 在工作流中使用
const workflow = {
nodes: [
{
id: 'analyze',
type: 'skill_custom_data-analyst', // 自动注册的节点类型
data: {
label: '数据分析',
config: {
skillId: 'data-analyst',
},
},
},
],
};
const executor = new WorkflowExecutor(workflow, {}, {
userId: 'user-123',
workspaceId: 'ws-456',
tenantId: 'tenant-789',
});
const result = await executor.execute({
data: csvData,
analysisType: 'full',
});
console.log(result.outputs.result); // 分析报告
示例3: 切换不同的LLM提供商
// 使用Claude (默认)
const result1 = await llmService.complete({
provider: 'anthropic',
model: 'claude-3-5-sonnet-20241022',
messages: [
{ role: 'user', content: 'Explain quantum computing' },
],
});
// 使用OpenAI
const result2 = await llmService.complete({
provider: 'openai',
model: 'gpt-4o',
messages: [
{ role: 'user', content: 'Explain quantum computing' },
],
});
// 使用Kimi（中文优化）
const result3 = await llmService.complete({
provider: 'kimi',
model: 'moonshot-v1-32k',
messages: [
{ role: 'user', content: '解释量子计算' },
],
});
// 使用Zhipu（中文大模型）
const result4 = await llmService.complete({
provider: 'zhipu',
model: 'glm-4',
messages: [
{ role: 'user', content: '解释量子计算' },
],
});
// 使用OpenRouter（访问多种模型）
const result5 = await llmService.complete({
provider: 'openrouter',
model: 'anthropic/claude-3-opus',
messages: [
{ role: 'user', content: 'Explain quantum computing' },
],
});
环境变量配置
所有API密钥已配置在 .env.local 文件中：
# Anthropic Claude
ANTHROPIC_API_KEY=sk-ant-api03-...
# OpenAI
OPENAI_API_KEY=sk-proj-...
# Google AI Studio
GOOGLE_API_KEY=AIzaSyC...
# OpenRouter
OPENROUTER_API_KEY=sk-or-v1-...
# SiliconFlow
SILICONFLOW_API_KEY=sk-mfb...
# Kimi (Moonshot)
KIMI_API_KEY=sk-LLC...
# Zhipu BigModel
ZHIPU_API_KEY=5318...
# Poe
POE_API_KEY=qwcv...
# ElevenLabs
ELEVENLABS_API_KEY=sk_3dd...
# MCP配置
MCP_ENABLED=true
MCP_TIMEOUT=30000
# Skill配置
SKILL_ENABLED=true
SKILL_TIMEOUT=60000
测试API端点
1. 测试MCP连接
curl -X POST http://localhost:3000/api/mcp/servers/filesystem/connect \
-H "Content-Type: application/json" \
-d '{
"config": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
}
}'
2. 测试获取工具
curl http://localhost:3000/api/mcp/servers/filesystem/tools
3. 测试调用工具
curl -X POST http://localhost:3000/api/mcp/servers/filesystem/call-tool \
-H "Content-Type: application/json" \
-d '{
"name": "read_file",
"arguments": {
"path": "/tmp/test.txt"
}
}'
4. 测试Skill执行
curl -X POST http://localhost:3000/api/skills/execute \
-H "Content-Type: application/json" \
-d '{
"skillId": "test-skill",
"inputs": {
"question": "What is 2+2?"
},
"instructions": "You are a helpful assistant. Answer the question accurately.",
"options": {
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022"
}
}'
错误处理
所有API端点都返回标准的错误格式：
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": "Stack trace (仅在开发环境)"
}
}
常见错误码:
SERVER_NOT_CONNECTED- MCP服务器未连接EXECUTION_ERROR- 工具/Skill执行失败VALIDATION_ERROR- 参数验证失败
性能优化建议
1. 使用连接池
MCP客户端会在服务端保持连接，避免重复连接开销。
2. 缓存工具列表
工具列表可以缓存，定期刷新即可：
const mcpManager = initializeMCPManager({
toolsRefreshInterval: 60000, // 每分钟刷新一次
});
3. 选择合适的模型
- 快速响应: gpt-4o-mini, claude-3-haiku
- 高质量: claude-3-5-sonnet, gpt-4o
- 长文本: moonshot-v1-32k, claude-3-opus
- 中文优化: kimi, zhipu, qwen
4. 并发控制
使用队列控制并发请求数：
const pLimit = require('p-limit');
const limit = pLimit(5); // 最多5个并发
const results = await Promise.all(
requests.map(req => limit(() => llmService.complete(req)))
);
总结
✅ MCP系统已完全打通，可以连接任何MCP服务器并调用其工具 ✅ Skill系统已完全打通，支持6种LLM提供商 ✅ 所有API密钥已配置完成，可直接使用 ✅ 插件适配器会自动将MCP工具和Skills转换为工作流节点
系统现在可以实际运行和执行真实的AI任务！
猪哥云（四川）网络科技有限公司 | 合规网 www.hegui.com 猪哥云-数据产品部-Maurice | [email protected] 2025 猪哥云-灵阙企业级智能体平台
深度加工（NotebookLM 生成）
基于本文内容生成的 PPT 大纲、博客摘要、短视频脚本与 Deep Dive 播客，用于多场景复用
PPT 大纲（5-8 张幻灯片） 点击展开
后端API集成指南 — ppt
这是一份基于您提供的《后端API集成指南》为您生成的 PPT 大纲。包含 7 张幻灯片，每张包含标题和要点，并附有内容来源引用：
幻灯片 1：后端 API 集成指南概述
- 文档目标：说明如何使用已实现的后端 API 端点，为 MCP 和 Skill 系统提供真实的执行能力 [1]。
- 密钥就绪：所有 API 密钥（如 OpenAI、Claude 等）已在
.env.local文件中配置完成，可直接使用 [2]。 - 系统现状：系统现已完全打通，能够实际运行并执行真实的 AI 任务 [3]。
- 项目背景：来源于2025年猪哥云-灵阙企业级智能体平台数据产品部 [3]。
幻灯片 2：已集成的核心 LLM 提供商
- 高质量与通用大模型：包含 Anthropic Claude（提供高质量推理与长文本处理）和 OpenAI GPT（用于通用对话与代码辅助）[1]。
- 中文优化专属模型：集成 Kimi (Moonshot)、Zhipu BigModel (智谱) 及 SiliconFlow（如 Qwen2、DeepSeek），强力支持中文与长上下文 [1]。
- 多模型聚合路由：通过 OpenRouter 和 Poe 接口，能够灵活访问多种开源和闭源模型 [1]。
- 特色功能模型：引入 Google AI Studio (Gemini 系列) 及 ElevenLabs (TTS 音频生成) [1]。
幻灯片 3：MCP (模型上下文协议) API 集成
- 连接服务器：通过
POST /api/mcp/servers/:serverId/connect端点建立 MCP 系统连接 [1]。 - 获取与调用工具：提供专属端点以获取文件读取等工具列表，并通过
call-tool提交参数以执行具体工具 [4]。 - 自动化注册节点：加载 MCP 适配器后，系统会自动将 MCP 工具转换为工作流节点，方便在代码中直接编排使用 [5]。
- 命令行测试：提供标准的
curl命令测试集，方便开发者随时验证连接、获取和调用工具的状态 [6]。
幻灯片 4：Skill API 系统与执行流程
- 标准化执行端点：通过
POST /api/skills/execute请求体提交输入数据、指令以及期望的 LLM 提供商和模型 [4, 5]。 - 自定义 Skill 加载：支持通过代码注册自定义的 Skill 加载器（如数据分析），灵活定义必需的输入与输出格式 [7]。
- 工作流无缝集成：与 MCP 类似，Skill 适配器会自动将其注册为工作流节点（如
skill_custom_data-analyst），实现快速调用 [7, 8]。 - 多模型自由切换：在代码调用中，可按需随意切换 Claude、OpenAI、Kimi、Zhipu 等底层驱动模型 [2, 8]。
幻灯片 5：全局错误处理与配置机制
- 标准错误格式：所有端点统一返回标准化的 JSON 错误格式，包含成功状态、错误代码、可读信息及开发环境的堆栈追踪 [3, 6]。
- 常见错误代码：系统预设了清晰的异常分类，如
SERVER_NOT_CONNECTED（未连接）、EXECUTION_ERROR（执行失败）和VALIDATION_ERROR（验证失败）[3]。 - 统一环境变量：通过
.env.local统一管理各大模型的 API Key，以及 MCP 和 Skill 的启用状态及超时时长设置 [2, 6]。
幻灯片 6：系统性能优化策略
- 连接与缓存优化：建议使用连接池保持服务端连接，并设置定期刷新（如 60000 毫秒）来缓存工具列表，减少系统开销 [3]。
- 精准的模型选择：根据业务场景选择最适模型，如快速响应选
gpt-4o-mini，长文本选moonshot-v1-32k，中文场景选kimi或zhipu[3]。 - 并发控制机制：建议使用
p-limit等队列工具控制并发请求数（如限制最多5个并发），以保障高并发下的稳定性 [3]。
幻灯片 7：总结与核心成果
- 全栈打通：MCP 系统与 Skill 系统均已完全打通，顺利连接服务器并支持调用任意 6 种以上 LLM 提供商 [3]。
- 开箱即用：所有核心配置与 API 密钥已就位，结合插件适配器实现节点的自动转换，极大降低了工作流搭建门槛 [3]。
- 业务赋能：该套件为灵阙企业级智能体平台提供了扎实的底层支撑，确保复杂 AI 任务的可靠执行 [3]。
博客摘要 + 核心看点 点击展开
后端API集成指南 — summary
SEO 友好博客摘要
欢迎阅读《后端API集成指南》！本文深入解析了如何将MCP（Model Context Protocol）与Skill系统完美融合，为企业级智能体平台提供强大的真实执行能力[1, 2]。文章详细展示了如何无缝接入OpenAI、Claude、Kimi、智谱等多款顶尖大模型（LLM），满足从代码生成到长文本处理的全方位业务需求[1, 3]。此外，本文提供了丰富的实战代码示例，演示了如何通过插件适配器将MCP工具与自定义Skill自动转化为工作流节点[4, 5]。结合连接池、缓存及并发控制等核心性能优化建议，助您轻松打造高效、稳定的AI工作流后端架构[2]！
核心看点
- 多模型无缝接入：全面集成并支持随时切换国内外主流LLM（如Claude、OpenAI、Kimi等）[1, 6]。
- 自动化工作流融合：MCP工具与Skill系统已全面打通，通过插件适配器自动转化为工作流节点执行[2, 4]。
- 企业级性能优化：提供连接池机制、工具列表缓存与并发请求队列控制，保障系统高效稳定运行[2]。
60 秒短视频脚本 点击展开
后端API集成指南 — video
AI系统如何执行真实任务？[1]
集成Claude等大模型，支持高质量推理及中文优化处理。[1, 2]
MCP系统已打通，能连接服务器调用工具，自动转为工作流节点。[1, 3]
Skill系统全面上线，支持执行自定义分析，提供高效并发优化。[1, 4]
各类API配置就绪，系统现可直接运行真实的AI任务！[1]
课后巩固
与本文内容匹配的闪卡与测验，帮助巩固所学知识
延伸阅读
根据本文主题，为你推荐相关的学习资料