Hugging Face's logo

Spaces:
StarrySkyWorld
/
InterConnectServer
Sleeping

App Files Community
InterConnectServer / docs /AI_API.md
GitHub Actions
Sync from GitHub (excluding README)
e9a82dd
preview code
|
raw
history blame contribute delete
8.04 kB

InterConnect-Server AI API Documentation

本文档描述了 InterConnect-Server 的 AI 聊天功能相关 API 接口。

概述

AI 功能允许 Minecraft 服务器通过 InterConnect-Client 插件/模组调用 OpenAI 格式的 API，实现游戏内 AI 聊天功能。

基础路径: /api/ai

认证

所有 API 请求需要在 Header 中携带 API Key：

Authorization: Bearer <your_api_key>

权限要求

接口 权限要求
GET /api/ai/config Admin Key
POST /api/ai/config Admin Key
PATCH /api/ai/config Admin Key
DELETE /api/ai/config Admin Key
POST /api/ai/config/test Admin Key
POST /api/ai/chat Server Key 或 Admin Key

AI 配置接口

获取 AI 配置

获取当前的 AI 配置信息（API Key 会被部分隐藏）。

请求

GET /api/ai/config
Authorization: Bearer <admin_key>

成功响应 200 OK

{
  "apiUrl": "https://api.openai.com/v1/chat/completions",
  "modelId": "gpt-3.5-turbo",
  "apiKey": "sk-x****xxxx",
  "enabled": true,
  "systemPrompt": "You are a helpful assistant for Minecraft players.",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T12:00:00.000Z"
}

错误响应 404 Not Found

{
  "detail": "AI configuration not found"
}

创建 AI 配置

创建新的 AI 配置。

请求

POST /api/ai/config
Authorization: Bearer <admin_key>
Content-Type: application/json

请求体

{
  "api_url": "https://api.openai.com/v1/chat/completions",
  "model_id": "gpt-3.5-turbo",
  "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx",
  "enabled": true,
  "system_prompt": "You are a helpful assistant for Minecraft players."
}
字段 类型 必填 说明
api_url string ✅ OpenAI 格式的 API URL
model_id string ✅ 模型 ID (如 gpt-3.5-turbo, gpt-4)
api_key string ✅ API Key
enabled boolean ❌ 是否启用，默认 true
system_prompt string ❌ 系统提示词，可选

成功响应 201 Created

{
  "apiUrl": "https://api.openai.com/v1/chat/completions",
  "modelId": "gpt-3.5-turbo",
  "apiKey": "sk-x****xxxx",
  "enabled": true,
  "systemPrompt": "You are a helpful assistant for Minecraft players.",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

错误响应 400 Bad Request

{
  "detail": "api_url, model_id, and api_key are required"
}

更新 AI 配置

更新现有的 AI 配置，只需提供要更新的字段。

请求

PATCH /api/ai/config
Authorization: Bearer <admin_key>
Content-Type: application/json

请求体

{
  "model_id": "gpt-4",
  "enabled": false
}
字段 类型 必填 说明
api_url string ❌ OpenAI 格式的 API URL
model_id string ❌ 模型 ID
api_key string ❌ API Key（不提供则保持原值）
enabled boolean ❌ 是否启用
system_prompt string ❌ 系统提示词

成功响应 200 OK

{
  "apiUrl": "https://api.openai.com/v1/chat/completions",
  "modelId": "gpt-4",
  "apiKey": "sk-x****xxxx",
  "enabled": false,
  "systemPrompt": "You are a helpful assistant for Minecraft players.",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T14:00:00.000Z"
}

删除 AI 配置

删除 AI 配置。

请求

DELETE /api/ai/config
Authorization: Bearer <admin_key>

成功响应 204 No Content

无响应体

错误响应 404 Not Found

{
  "detail": "AI configuration not found"
}

测试 AI 连接

测试当前 AI 配置是否能正常连接。

请求

POST /api/ai/config/test
Authorization: Bearer <admin_key>

成功响应 200 OK

{
  "success": true,
  "message": "Connection successful",
  "model": "gpt-3.5-turbo",
  "response": "OK"
}

错误响应 400 Bad Request

{
  "success": false,
  "message": "Connection failed",
  "error": "Invalid API key"
}

AI 聊天接口

发送聊天消息

发送消息到 AI 并获取回复。此接口供 Minecraft 服务器的 InterConnect-Client 插件/模组调用。

请求

POST /api/ai/chat
Authorization: Bearer <server_key>
Content-Type: application/json

请求体

{
  "message": "你好，请介绍一下 Minecraft 的红石系统",
  "player_name": "Steve",
  "server_id": "my-server-1"
}
字段 类型 必填 说明
message string ✅ 用户发送的消息内容
player_name string ❌ 发送消息的玩家名称
server_id string ❌ 服务器 ID（Admin Key 可指定，Server Key 使用绑定的 server_id）

成功响应 200 OK

{
  "success": true,
  "reply": "红石是 Minecraft 中的一种特殊材料，可以用来创建各种机械装置...",
  "model": "gpt-3.5-turbo",
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

错误响应

404 Not Found - AI 配置不存在

{
  "detail": "AI configuration not found"
}

403 Forbidden - AI 功能已禁用

{
  "detail": "AI feature is disabled"
}

400 Bad Request - 缺少必填字段

{
  "detail": "message is required"
}

500 Internal Server Error - AI 请求失败

{
  "success": false,
  "detail": "AI request failed",
  "error": "Rate limit exceeded"
}

事件类型

当 AI 聊天发生时，会产生 ai_chat 类型的事件，通过 WebSocket 广播给所有连接的客户端。

事件格式

{
  "type": "minecraft_event",
  "event": {
    "event_type": "ai_chat",
    "server_name": "my-server-1",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "data": {
      "player_name": "Steve",
      "message": "你好",
      "reply": "你好！有什么我可以帮助你的吗？",
      "model": "gpt-3.5-turbo"
    }
  },
  "source_key_id_prefix": "abc12345"
}

Minecraft 插件/模组集成示例

命令格式

在 Minecraft 服务器中，玩家可以使用以下命令调用 AI：

/ic chat <消息内容>

插件实现流程

  1. 玩家执行 /ic chat 你好 命令
  2. 插件捕获命令，提取消息内容
  3. 插件向 InterConnect-Server 发送 POST 请求：
POST /api/ai/chat
Authorization: Bearer <server_key>
Content-Type: application/json

{
  "message": "你好",
  "player_name": "Steve",
  "server_id": "my-server-1"
}
  1. 收到响应后，将 AI 回复发送给玩家

响应处理示例（伪代码） 

// 发送请求
Response response = httpClient.post("/api/ai/chat", {
    "message": playerMessage,
    "player_name": player.getName(),
    "server_id": serverId
});

// 处理响应
if (response.success) {
    player.sendMessage("[AI] " + response.reply);
} else {
    player.sendMessage("[AI] 请求失败: " + response.error);
}

支持的 API 提供商

本系统支持所有兼容 OpenAI Chat Completions API 格式的服务：

提供商 API URL 示例
OpenAI https://api.openai.com/v1/chat/completions
Azure OpenAI https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version=2024-02-01
Anthropic (via proxy) 需要兼容层
本地模型 (Ollama) http://localhost:11434/v1/chat/completions
其他兼容服务 根据服务商文档配置

错误码参考

HTTP 状态码 说明
200 请求成功
201 创建成功
204 删除成功（无内容）
400 请求参数错误
401 未认证或 API Key 无效
403 权限不足或功能已禁用
404 资源不存在
500 服务器内部错误