AI数据库wAPI核心
适用于Minecraft 1.21.1 (NeoForge)的核心服务端模组,支持异步外部AI API调用和基于JSON的轻量级数据存储。它为其他模组提供API,无独立功能。
AI DataBase wAPI Core (aidbwapi_core)
一个面向 Minecraft 1.21.1 (NeoForge) 的核心服务端模组,为外部 AI(兼容 OpenAI 的 LLM API)提供异步请求功能,以及基于 JSON 的轻量级持久化存储(数据库功能)。
本模组本身不提供独立完整的功能(如聊天机器人等),而是被设计为一个系统基础设施(Core),让其他模组(依赖模组)能够通过 Java API(AiCoreAPI / DatabaseManager)轻松利用高级 AI 功能与数据存储能力。
🚀 核心功能与架构 (Features & Architecture)
1. AI Request Network(高级 AI 集成与自主故障转移)
内置自主故障转移与限流系统,在将服务器负载降至最低的同时,安全可靠地运营与外部 API 的通信(保证 AI 不停止的机制)。
完全异步处理与串行队列 (Async Executor): 对 AI 的所有 HTTP 请求均使用
CompletableFuture与 Java 标准HttpClient机制(异步 I/O 处理)执行,绝不阻塞 Minecraft 的 Tick。此外,采用“并发执行数始终最多为 1(队列管理)”的安全设计,避免对同一提示词字符串进行多重并发发送。延迟评估重置 (Lazy Reset): 模型的“每日执行上限”与“每分钟执行上限”的初始化判定,不依赖服务器的定期处理(常时监视),而是采用“延迟评估(Lazy Reset)”机制:在下一次请求发生的瞬间通过时间戳比较来逐次计算与重置,待机时的服务器负载为零。
密钥分散运用与分布式轮询 (Priority & Load Balancing): 可对同一提供商或模型注册多个 API 密钥。可为每个模型(ModelEntry)设置优先级(
priority:数值越小优先级越高),在达到速率上限或发生错误时,系统会自动按优先级从高到低进行故障转移(自动切换到其他模型/其他密钥)。 此外,当存在多个相同优先级的模型时,系统会以“轮询(Round-Robin)方式”分散去向,自动防止负载集中于特定 API 密钥。可将多个免费 API 的速率限制额度通过多个密钥合算后安全运营。惩罚点数(PP)制与概率跳过 (Penalty System): 发生通信错误等时,不会立即将目标模型无效化,而是施加临时冷却秒数(默认:429=60 秒,5xx=120 秒,Timeout=60 秒,连接失败=300 秒),同时根据错误严重程度累加惩罚点数(PP)。
HTTP 429(速率限制):+1 PPHTTP 5xx(服务器错误):+5 PPTimeout/ 连接・DNS 解析失败:+7 PP- 通信成功时:PP 减半(
PP /= 2)
在选出执行候选时,持有 PP 的模型会以
PP / (PP + 4.0)的概率被暂时跳过(转移到次优模型),从而自主回避・抑制对状态不佳的端点的访问。最多 100 轮的故障安全循环 (Fail-Safe Loop): 当所有模型候选都处于概率跳过或冷却中时,会回到候选列表开头进行重新抽选循环,为防止无限循环,设有强固的故障安全机制:“最多 100 轮后强制中止,要么妥协选出可用模型中优先级最高(priority 最小)的模型,要么向 API 层返回完全失败”。
异常处理 (HTTP 400 Bad Request): 当发生
HTTP 401(认证错误)或HTTP 404(模型不存在)这类配置不良错误时,系统会自动将目标模型本身无效化(disabled),随后立即故障转移到下一个模型候选(重试)。然而对于HTTP 400(请求非法),由于“提示词或发送数据的结构本身存在 bug”,无论切换到哪个模型都很可能失败,因此不进行故障转移,而是立即向调用方的依赖模组返回错误(即时中止无用的循环)。
2. JSON Storage System(数据库功能)
这是一个让依赖模组能够极其简单地保存・读取自身数据的基础设施。保存格式完全固定为 JSON。
- 分类注册与层级管理:
依赖模组(外部模组)在初始化时调用
registerCategory("my_mod"),即可自动生成与该分类名绑定的目录结构。“通用数据(Global)”与“玩家个别(UUID)数据”会自动分配到不同文件夹保存。(※未事先注册则无法保存数据)。 - 内存缓存与动态解析:
频繁访问的数据在读取时会作为 Map 缓存到内存中,之后的
get/set无需磁盘访问(I/O)即可立即处理。保存目录的根路径会在服务器启动事件(ServerStartedEvent)中自动获取如root/world/aidbwapi_core/等正确路径后确定。 - 同步・即时保存机制:
对数据库进行写入(调用
set())时,会在更新内存缓存的同时立即执行同步文件写入(flush)。(※仅错误日志输出使用后台每 3 小时的延迟计时器,但 DB 本身不存在异步自动保存的延迟功能)。为安全起见,也实现了手动强制保存(db save)命令。
💻 运行要求与安装 (Requirements & Setup)
- Minecraft: 1.21.1
- Mod Loader: NeoForge 21.1.219 或更高版本
- Java: Java 21 或更高版本
- 端: 服务端与客户端均必需
安装:
将本模组(aidbwapi_core-x.x.x.jar)放入服务器或客户端的 mods 文件夹后启动。
⚙️ 配置文件与目录结构 (Configuration)
所有配置、数据库与错误日志都会展开在服务器根目录,或客户端的 saves/[世界名]/ 下。
config/aidbwapi_core-common.toml:整个模组的基础运行设置文件。commandPermissionLevel:所有/dbwapi命令所需的 OP 权限等级(默认2)。可改为 0〜4。requestTimeoutSeconds:AI 通信的响应超时秒数(默认60秒)。penaltyCurveFactor:PP 跳过概率计算曲线的调整系数(默认4.0)。- 此外,还可设置各种 HTTP 错误时的冷却秒数(
rateLimitSeconds等),以及错误日志的定期 flush 间隔(flushIntervalMinutes)等。部分基础设置可通过游戏内命令(/dbwapi config ...等)即时修改并持久化。
config/aidbwapi_core-keynames.json:以结构化方式保存 AI 端点 URL、API 密钥明文、模型列表以及各种速率限制(dailyLimit、minuteLimit)设置。- ⚠️【重要】关于 API 密钥的安全性与注册方法
作为模组的规格,API 密钥本身不会被加密,而是以明文保存在该 JSON 文件内(前提是通过
.gitignore等防护或依赖操作系统服务器权限进行保护运营)。虽然也可通过游戏内命令(/dbwapi keyname setkey)注册,但由于 Minecraft 的规格,你在聊天栏输入的完整命令(API 密钥明文字符串)会原样、清晰地记录到服务器的logs/latest.log以及控制台画面的日志文件中。 为确保安全,在运营可能对外提供的服务器时,请避免在游戏内输入命令,而是强烈推荐直接用文本编辑器打开本文件,修改・保存"apiKey": "sk-xxxx...",然后在游戏内执行/dbwapi reload命令重新加载。
- ⚠️【重要】关于 API 密钥的安全性与注册方法
作为模组的规格,API 密钥本身不会被加密,而是以明文保存在该 JSON 文件内(前提是通过
[世界保存根目录]/aidbwapi_core/[分类名]/:经由CategoryDatabaseHandle等保存・缓存的各分类的设置・数据保存根目录。- 分类直下会放置通用数据(
global.json)以及玩家个别文件夹(players/<UUID>.json)。
- 分类直下会放置通用数据(
[世界保存根目录]/aidbwapi_core/log/:内存中累积的 AI・DB 处理时错误历史(调试日志)在后台以 JSON 格式输出的输出目标。- 最新的错误日志输出默认最多保留
20个文件,较旧的会自动轮换(删除)。 - 此外,内存中残留的未保存错误状态会在服务器结束・关闭时(
ServerStoppingEvent)被插队 flush,确保抢救・保存到磁盘。
- 最新的错误日志输出默认最多保留
🛠️ 命令参考 (Command Reference)
AI 的初始设置以及模型的各种设置・管理,都可以通过游戏内命令轻松完成。
所有命令均以 /dbwapi 开头。(默认要求权限:common.toml 中记载的等级。初始值为 2)
- 参数・补全的规格: 输入标识符(KeyName 或 Model 名)时,所有已注册设置都会在游戏内提供补全(Tab 补全)显示。语法错误或参数不足将按 Brigadier 标准被拒绝。
- 消息格式显示颜色: 命令的所有反馈均作为系统消息以
[AiDb](绿色)开头,操作对象(数值或名称)以黄色高亮。错误与警告整体以红色文本输出。 - API 密钥等输出保护的彻底执行: 当通过画面显示命令(
info或list)等将 API 密钥信息输出到聊天栏时,为保护起见,仅以“若原密钥为 5 个字符或以上,则仅显示前 4 个字符,其余所有字符用****遮蔽”“若原密钥为 4 个字符或以下,则作为例外用****遮蔽所有字符”的状态显示,原始密钥绝不会输出到画面。此外,在系统日志输出等时也完全不会包含密钥。
📌 通用 (General & Config)
/dbwapi status:整个系统的运行摘要。显示已加载的 KeyName 数与模型数,以及在内存中处于待输出状态(Queue)的 AI 错误・DB 错误件数。/dbwapi reload:强制重新加载 TOML 及 JSON(keynames.json)配置文件。手动编辑文本后务必执行。/dbwapi version:显示本模组的版本。/dbwapi config show:显示当前应用的调试日志设置(debugLogging)与 AI 通信超时秒数(requestTimeoutSeconds)。/dbwapi config debug true|false:即时切换・持久化调试等级(详细日志输出)的开关。/dbwapi config timeout <秒>:修改・持久化 AI 通信的超时秒数(基础设置)。
📌 密钥 (KeyName) 管理 (KeyName Management)
将 URL(提供商端点)与 API 密钥的组合,作为系统通用的**“注册名(keyName)”**进行集中管理。
/dbwapi keyname list/info <keyName>:显示已注册的所有 KeyName 列表,或指定 KeyName 的详情。(API 密钥会被遮蔽)/dbwapi keyname add <keyName> <apiUrl> <apiKey>:为新 AI 提供商(兼容 OpenAI)注册连接信息组合。※注册名(keyName)重复会报错,但允许将相同内容的apiUrl与apiKey以不同名称注册多个(用于负载均衡)。/dbwapi keyname seturl <keyName> <apiUrl>:仅更新现有 KeyName 的 API 端点 URL。/dbwapi keyname setkey <keyName> <apiKey>:更新现有 KeyName 的 API 密钥。(※存在前述的日志残留风险。为安全起见,推荐直接编辑 JSON。)/dbwapi keyname remove <keyName> [confirm]:带防误操作安全装置的删除。若省略末尾参数([confirm])或使用false执行,则仅输出删除确认的警告日志后结束。只有在末尾明确指定true时,才会完全删除 KeyName(以及该 KeyName 绑定的所有模型设置群)。
📌 模型管理 (Model & Failover Management)
模型的标识符始终以能辨明属于哪个提供商的 <keyName>.<模型名>(例:taro_groq.llama-3-70b 这样用点分隔)形式指定。
/dbwapi model list/info <keyName>.<模型名>:显示所有模型的运行状况(优先级、惩罚・PP 状况、当前是否有效等)以及个别模型的详细限制指标。/dbwapi model add <keyName>.<模型名> [dailyLimit:日次上限] [minuteLimit:分间上限]:为父 KeyName 添加新的可用模型。若省略上限参数,或输入-1,则注册为“日次/分次均无限制”。/dbwapi model move <keyName>.<模型名> up|down:将指定模型的优先级(Priority 排序)上移(up)或下移(down)一级・互换。/dbwapi model limit <keyName>.<模型名> daily|minute <值>:更改模型的次数上限(-1为无限制)。设定更改即时生效。/dbwapi model enable <keyName>.<模型名>/disable <keyName>.<模型名>:启用/临时禁用指定模型的抽选设置。- 【从自动无效化中恢复】:当发现例外(
HTTP 401/403 Invalid API Key或HTTP 404 Not Found)等永久性失败的配置问题时,系统会自动将目标模型强制无效化(disabled)。解决端点不一致等(seturl等)后,请通过此enable命令手动恢复。
- 【从自动无效化中恢复】:当发现例外(
/dbwapi model reset <keyName>.<模型名>:立即将目标模型累积的 PP(惩罚)与冷却状态重置为零。/dbwapi model resetall:一次性重置当前注册的“所有模型”。/dbwapi model remove <keyName>.<模型名> [confirm]:删除指定模型。(※带安全装置。末尾必须为true)
📌 AI 动作测试・错误日志・DB 管理 (Tests & Logger)
/dbwapi ai status:显示当前执行・处理中(Active)的请求,以及进入异步处理等待队列(Queue)的 AI 请求件数。/dbwapi ai test:利用“当前有效的模型(优先级最高且可通信者)”,从系统向 AI 发送数十个字符的简短测试提示词,进行是否实际返回文本回复的连通(结合)测试。/dbwapi ai errors [显示件数]:将队列中累积的“最近发生的 AI 通信错误(HTTP 状态码与原因异常等)”历史,连同时间・目标模型名一起,最多 50 件(省略时默认 10 件)快速输出到聊天栏。便于定位错误。/dbwapi ai errors clear:清空画面显示用的错误历史内存。(※磁盘上的日志文件本身不会被删除)/dbwapi db list:显示依赖模组等当前注册到DatabaseManager的所有分类名列表。/dbwapi db info <分类名>:显示目标分类的保存根路径、全局 DB 的键数(已加载的规模感),以及当前缓存中的每位玩家 UUID 数据总数等指标。/dbwapi db errors [件数]/db errors clear:与ai errors相同机制,将 DB 特有的日志(FILE_WRITE_ERROR等)输出到聊天栏(省略时默认 10 件)・清除。/dbwapi db save:将内存上所有数据库的更改内容显式强制写入文件(flush)。(※通常set时会自动即时同步保存,此命令用于直接篡改内存后的抢救用途)。
📦 面向开发者:Java API 的实现使用方法 (API Layer for Developers)
本 Core 基础设施由依赖模组(自制模组等)的 Java 代码,通过单例(getInstance())或各种 Static 方法调用使用。请在 build.gradle 中将 aidbwapi_core 纳入依赖解析(compileOnly 等)后再实现。
1. 向 AI 发起异步请求 (AiCoreAPI)
内部完全隐藏了速率限制检查、密钥分配、故障转移、异常处理管线。 调用方开发者只需“投递提示词字符串,通过 CompletableFuture 接收结果字符串”即可完成,设计极为简洁。
import com.morwapi.aidbwapi_core.api.AiCoreAPI;
// 执行结果会作为 CompletableFuture<String> 异步返回。
AiCoreAPI.getInstance().requestAI("用100个字告诉我Minecraft的魅力")
.thenAccept(response -> {
// [成功时] 获取并处理 AI 的响应字符串(response)。
System.out.println("AI的回答: " + response);
// ⚠️【注意】此处运行在“独立线程(AsyncExecutor内部)”。
// 若要安全访问 Minecraft 世界(发送聊天、放置方块、实体操作等),
// 必须使用 server.execute(() -> { ... }) 等任务队列,
// 确保将处理返回到主线程(Server Thread)。
})
.exceptionally(ex -> {
// [失败・异常时] 已注册的所有模型均不可用(全灭)、重试超过100件、
// 或请求参数非法(HTTP 400)等完全失败时到达此处。
// 错误种类(RATE_LIMITED, ALL_FAILED 等)与详情包含在消息(ex.getMessage())中。
System.out.println("AI通信错误: " + ex.getMessage());
return null; // CompletableFuture要求
});
2. JSON 数据库与分类 (CategoryDatabaseHandle)
经由 AiCoreAPI 注册・获取分类,接收 PlayerDatabase 或 GlobalDatabase 的句柄,进行数据的保存・读取。
【重要】JsonStorageEngine 的规格与类型:
本 DB 并非直接保存・完全还原自有复杂类结构(POJO)的高功能 ORM 工具。受 Gson 规格等影响,从 JSON 文件通过 get() 展开(还原)的数据全部会作为 Map<String, Object>(或原始类型)的集合加载。
因此,保存时可以自行传入自有类实例,但读取时前提是从 Map 或标准类型自行强制转换・重建(或另行用 Gson 反序列化),这是极其简洁的功能设计。推荐基于简单的 Map、数值或字符串使用。
import com.morwapi.aidbwapi_core.api.AiCoreAPI;
import com.morwapi.aidbwapi_core.api.CategoryDatabaseHandle;
import java.util.UUID;
// ------ 模组初始化时 (FMLCommonSetupEvent等) ------
// [1]. 分类的自动生成・注册
AiCoreAPI.getInstance().registerCategory("guild_mod");
// [2]. 获取操作用的DB句柄
CategoryDatabaseHandle dbHandle = AiCoreAPI.getInstance().getCategoryDatabase("guild_mod");
// ------ 实现示例 (PlayerJoinEvent等) ------
UUID playerId = player.getUUID();
// [1]. 数据加载 (读取)
// 会从 JSON 以 Map 等形式还原。未创建时返回 null。
Object rawData = dbHandle.getPlayerDB().get(playerId, "killCount");
int killCount = 0;
if (rawData != null) {
// 由于 Gson 可能将数值变为 Double 等,需以 Number 类型接收并强制转换
killCount = ((Number) rawData).intValue();
}
// [2]. 数据更新与保存 (保存)
killCount += 1;
// 参数:玩家UUID, 保存识别键名, 保存的值(Object)
dbHandle.getPlayerDB().set(playerId, "killCount", killCount);
// ※调用此 `set()` 方法的瞬间,会在应用于内存(缓存侧 Map)的同时,
// 【同步且即时地】将文件写出到 `guild_mod/players/<UUID>.json`。
⚖️ 许可证 (License)
本模组的源代码及提供的二进制文件以 Apache License, Version 2.0 提供・发布。 使用・依赖本基础设施(API)的商业・非商业模组的创建与再分发,均可在许可证条款范围内自由进行。
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。