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 PP
    • HTTP 5xx(服务器错误):+5 PP
    • Timeout / 连接・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 命令重新加载。
  • [世界保存根目录]/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)的商业・非商业模组的创建与再分发,均可在许可证条款范围内自由进行。