- 英文 / 2. 日本語
AI DataBase wAPI Core (aidbwapi_core)
适用于 Minecraft 1.21.1 (NeoForge) 的核心服务端模组,提供与外部 AI(兼容 OpenAI 的 LLM API)进行异步请求的功能,以及基于轻量级 JSON 的持久化存储(数据库功能)。
该模组本身不提供独立功能(如聊天机器人);它被设计为系统基础设施(Core),允许其他模组(依赖模组)通过 Java API (AiCoreAPI / DatabaseManager) 轻松利用高级 AI 功能和数据存储。
? 特性与架构
1. AI 请求网络(高级 AI 集成与自动故障转移)
配备了自动故障转移和速率限制系统,旨在确保与外部 API 的安全可靠通信,同时最小化服务器负载。
-
全异步处理与串行队列 (Async Executor):
所有对 AI 的 HTTP 请求均使用 CompletableFuture 和 Java 标准 HttpClient 机制(异步 I/O)执行,确保不会阻塞 Minecraft 的 tick。此外,通过确保“并发执行数始终最多为一个(队列管理)”,防止同一提示词字符串的多次同时传输,从而保证安全性。
-
惰性求值重置 (Lazy Reset):
初始化时检查模型的“每日执行限制”和“每分钟执行限制”不使用周期性服务器任务(持续监控)。相反,它采用惰性重置机制,在下次请求发生时通过比较时间戳即时进行计算和重置,从而实现零待机服务器负载。
-
密钥分发与分布式轮询(优先级与负载均衡):
可以为同一提供商或模型注册多个 API 密钥。你可以为每个 ModelEntry 设置优先级(priority:值越低优先级越高)。在发生错误或速率限制耗尽的情况下,系统会自动回退(切换到下一个最高优先级的模型/密钥)。
此外,如果存在多个具有相同优先级的模型,系统将使用“轮询”方法分配请求,自动防止负载集中在特定的 API 密钥上。 这允许通过聚合多个免费 API 密钥的速率限制配额来安全运行。
-
惩罚点 (PP) 系统与概率跳过(惩罚系统):
当发生通信错误时,模型不会立即被禁用。而是根据错误的严重程度分配惩罚点 (PP),同时应用临时冷却时间(默认:429 = 60秒,5xx = 120秒,超时 = 60秒,连接失败 = 300秒)。
HTTP 429 (速率限制): +1 PP
HTTP 5xx (服务器错误): +5 PP
Timeout / 连接 / DNS 失败: +7 PP
- 通信成功: 减半 PP (
PP /= 2)
在选择执行候选项时,具有 PP 的模型将以计算出的概率暂时跳过:
$$\frac{PP}{PP + 4.0}$$
系统通过移动到下一个候选项,自主避免或抑制访问当前不稳定的端点。
-
100 轮故障保护循环:
如果所有候选模型当前都处于概率跳过或冷却状态,系统将循环回到候选列表开头以重新抽取。为防止无限循环,强大的故障保护会在最多 100 轮后终止进程,要么选择可用性最高的优先级模型(最低优先级值)作为妥协,要么向 API 层返回完全失败。
-
异常处理 (HTTP 400 错误请求):
如果发生配置相关错误,如 HTTP 401 (未经授权) 或 HTTP 404 (模型未找到),特定模型将自动禁用 (disabled),系统立即回退(重试)到下一个候选项。然而,对于 HTTP 400 (错误请求),由于问题可能是提示词或数据结构特有的 bug,切换模型不太可能成功。因此,系统在不进行故障转移的情况下立即向调用方依赖模组返回错误(无用的循环即时终止)。
2. JSON 存储系统(数据库功能)
一个基础框架,使依赖模组能够极其轻松地保存和加载自己的数据。存储格式严格固定为 JSON。
- 类别注册与层级管理:
通过在初始化期间调用
registerCategory("my_mod"),依赖模组(外部模组)会自动生成与该类别名称链接的目录结构。数据会自动分类到“通用数据(全局)”和“单个玩家(UUID)数据”文件夹中。(注意:未经预先注册无法保存数据)。
- 内存缓存与动态解析:
经常访问的数据在加载时被缓存在内存中的 Map 中。随后的
get/set 操作会立即处理,无需磁盘 I/O。存储目录的根路径通过在 ServerStartedEvent 期间检索正确路径(例如 root/world/aidbwapi_core/)自动确定。
- 同步与即时保存机制:
当对数据库执行写入操作 (
set()) 时,内存缓存会更新并执行即时同步文件写入 (flush)。(注意:虽然错误日志每 3 小时使用后台延迟计时器,但数据库本身没有异步自动保存延迟功能)。为了安全起见,还实现了一个手动强制保存命令 (db save)。
? 要求与设置
- Minecraft: 1.21.1
- Mod Loader: NeoForge 21.1.219 或更高版本
- Java: Java 21 或更高版本
- Side: 服务器和客户端均需安装
安装:
将此模组 (aidbwapi_core-x.x.x.jar) 放入服务器或客户端的 mods 文件夹中并启动。
⚙️ 配置与目录结构
所有设置、数据库和错误日志均部署在服务器根目录或客户端的 saves/[world_name]/ 目录下。
config/aidbwapi_core-common.toml:整个模组的基本运行设置。
commandPermissionLevel:执行所有 /dbwapi 命令所需的 OP 等级(默认值:2)。可更改为 0 到 4 之间的任意值。
requestTimeoutSeconds:AI 通信响应的超时时间(默认值:60 秒)。
penaltyCurveFactor:PP 跳过概率曲线的调整系数(默认值:4.0)。
- 其他设置包括各种 HTTP 错误的冷却时间(如
rateLimitSeconds 等)以及错误日志的定期刷新间隔(flushIntervalMinutes)。部分基本设置可以通过游戏内命令即时更改并持久化保存。
config/aidbwapi_core-keynames.json:以结构化格式存储 AI 端点 URL、明文 API 密钥、模型列表以及各种速率限制设置(dailyLimit、minuteLimit)。
- ⚠️ [重要] API 密钥安全与注册方法
作为本模组的规范,API 密钥未加密,而是以明文形式保存在此 JSON 文件中。虽然可以通过游戏内命令(
/dbwapi keyname setkey)注册密钥,但由于 Minecraft 的规范限制,你在聊天栏中输入的完整命令(即明文 API 密钥字符串)将被原样记录在服务器的 logs/latest.log 和控制台日志文件中。
为确保安全,请避免使用游戏内命令输入。我们强烈建议直接使用文本编辑器打开此文件,编辑/保存 "apiKey": "sk-xxxx..." 字段,然后在游戏内运行 /dbwapi reload 命令以重新加载设置。
[World Save Root]/aidbwapi_core/[category_name]/:通过 CategoryDatabaseHandle 等保存和缓存的每个类别的设置和数据存储根目录。
global.json 用于通用数据,players/ 文件夹包含各个玩家的 <UUID>.json 文件,均直接位于该类别目录下。
[World Save Root]/aidbwapi_core/log/:内存中积累的 AI 和 DB 处理错误历史(调试日志)以 JSON 格式在后台导出的目标位置。
- 默认情况下仅保留最新的
20 个错误日志文件,旧文件会自动轮换(删除)。
- 任何残留在内存中的未保存错误状态都会在服务器关闭/终止时(
ServerStoppingEvent)被刷新,以确保保存到磁盘。
?️ 命令参考
初始 AI 设置和各种模型设置/管理可通过游戏内命令轻松完成。
所有命令均以 /dbwapi 开头。
- 参数与建议: 输入标识符(KeyName 或 Model 名称)时,会显示所有已注册设置的建议(Tab 补全)。语法错误或参数不足将按照 Brigadier 标准被拒绝。
- 消息格式颜色: 所有命令反馈均以
[AiDb] 开头(绿色)。操作的目标(值或名称)以黄色高亮显示。错误和警告以红色文本输出。
- API 密钥的严格输出保护: 当通过显示命令(
info 或 list)将 API 密钥信息输出到聊天栏时,会进行掩码处理以确保护: "如果原始密钥长度为 5 个字符或更长,则仅显示前 4 个字符,其余所有字符均用 **** 掩码隐藏。" "如果密钥长度为 4 个字符或更少,则所有字符均例外地用 **** 掩码隐藏。" 原始密钥绝不会输出到屏幕或日志中。
? 常规与配置
/dbwapi status:系统运行概况。显示已加载的 KeyNames 和 Models 数量,以及当前排队等待输出的 AI 和 DB 错误计数。
/dbwapi reload:强制重新加载 TOML 和 JSON(keynames.json)配置文件。手动文本编辑后请务必运行此命令。
/dbwapi version:显示本模组版本。
/dbwapi config show:显示当前应用的调试日志设置(debugLogging)和 AI 通信超时时间(requestTimeoutSeconds)。
/dbwapi config debug true|false:即时开启/关闭调试级别(详细日志输出)并持久化设置。
/dbwapi config timeout <seconds>:更改并持久化 AI 通信超时时间(基本设置)。
? KeyName 管理
集中管理系统范围的 “注册名称 (keyName)”,该名称由 URL(提供商端点)和 API 密钥组成。
/dbwapi keyname list / info <keyName>:显示所有已注册 KeyNames 的列表或特定 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]:安全锁定的删除操作。需要在末尾添加 true 才能执行。
? 模型与故障转移管理
模型标识符始终指定为 <keyName>.<model_name>(例如 taro_groq.llama-3-70b)。
/dbwapi model list / info <keyName>.<model_name>:显示所有模型的运行状态(优先级、惩罚/PP 状态、当前状态等)以及单个模型的详细限制指标。
/dbwapi model add <keyName>.<model_name> [dailyLimit] [minuteLimit]:向父级 KeyName 添加一个新的可用模型。使用 -1 表示无限制。
/dbwapi model move <keyName>.<model_name> up|down:将指定模型的优先级向上移动一级 (up) 或向下移动一级 (down)。
/dbwapi model limit <keyName>.<model_name> daily|minute <value>:更改模型的最大限制(-1 表示无限制)。更改立即生效。
/dbwapi model enable <keyName>.<model_name> / disable <keyName>.<model_name>:启用或临时禁用特定模型的抽奖设置。
- [自动禁用后的恢复]:如果发生端点配置问题(例如
HTTP 401/403 Invalid API Key 或 HTTP 404 Not Found),系统将自动强制禁用该模型(disabled)。在解决不匹配问题后(例如通过 seturl),使用此 enable 命令手动恢复它。
/dbwapi model reset <keyName>.<model_name>:立即将目标模型的累积 PP(惩罚)和冷却状态重置为零。
/dbwapi model resetall:一次性重置当前注册的所有模型。
/dbwapi model remove <keyName>.<model_name> [confirm]:删除指定的模型。(※ 需要安全锁定;末尾必须加上 true)。
? AI 测试、错误日志与数据库管理(测试与日志记录器)
/dbwapi ai status:显示当前正在处理的 AI 请求数(Active)和异步处理等待队列中的请求数(Queue)。
/dbwapi ai test:使用“当前有效模型”发送简短的测试提示,并检查是否实际返回了文本响应。
/dbwapi ai errors [count]:输出最近的 AI 通信错误历史记录(最多 50 条,默认为 10 条)。
/dbwapi ai errors clear:清除用于显示的错误历史记录内存。
/dbwapi db list:显示 DatabaseManager 中当前注册的所有类别名称列表。
/dbwapi db info <category>:显示指标,如存储根路径、全局 DB 键计数和当前玩家 UUID 缓存计数。
/dbwapi db errors [count] / db errors clear:与 ai errors 相同,但针对 DB 特定的日志(例如 FILE_WRITE_ERROR)。
/dbwapi db save:显式强制将所有数据库中内存中的所有更改写入文件(flush)。
? 面向开发者:Java API 实现(开发者的 API 层)
核心基础设施可通过从依赖模组的 Java 代码中调用单例 (getInstance()) 或各种静态方法来使用。请在实施前将 aidbwapi_core 包含在你的 build.gradle 作为依赖项(例如 compileOnly)。
1. 向 AI 发起异步请求 (AiCoreAPI)
所有内部速率限制检查、密钥分发、故障转移和异常处理管道均已隐藏。
import com.morwapi.aidbwapi_core.api.AiCoreAPI;
// 执行结果以 CompletableFuture<String> 的形式异步返回。
AiCoreAPI.getInstance().requestAI("用100个字符告诉我Minecraft的魅力")
.thenAccept(response -> {
// [成功时] 处理 AI 响应字符串 (response)。
System.out.println("AI Response: " + response);
// ⚠️ [注意] 这是在“独立线程(AsyncExecutor 内部)”中执行的。
// 为了安全地访问 Minecraft 世界(发送聊天、放置方块、实体操作等),
// 你必须确保使用类似 server.execute(() -> { ... }) 的任务队列将处理返回到主线程(服务器线程)。
})
.exceptionally(ex -> {
// [失败/异常时] 如果所有模型不可用、
// 重试限制(100次)超过或请求参数无效(HTTP 400),则进入此处。
System.out.println("AI Communication Error: " + ex.getMessage());
return null; // CompletableFuture 要求
});
### 2. JSON 数据库与类别 (`CategoryDatabaseHandle`)
通过 `AiCoreAPI` 注册和获取类别,并接收 `PlayerDatabase` 或 `GlobalDatabase` 的句柄以保存和读取数据。
**[重要] JsonStorageEngine 规范与类型:**
此数据库并非用于直接保存和完全恢复复杂自定义类结构(POJOs)的高性能 ORM 工具。由于 GSON 规范,通过 `get()` 从 JSON 文件恢复的所有数据都加载为 **`Map<String, Object>`**(或基本类型)的集合。
因此,虽然在保存时可以传递自定义类实例,但其设计极其简单,假设你在读取时会从 Maps 或标准类型进行转换或重建(或使用 GSON 单独反序列化)。建议仅与简单的 Maps、数字或字符串一起使用。
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、存储标识键名、要保存的值(对象)
dbHandle.getPlayerDB().set(playerId, "killCount", killCount);
// ※ 当调用此 `set()` 方法时,文件会 [同步且立即地] 写入到
// `guild_mod/players/<UUID>.json`,同时应用于内存(缓存端的 Map)。
## ⚖️ 许可证 (License)
本模组的源代码及提供的二进制文件均在 **Apache License, Version 2.0** 下提供并发布。
在许可证条款范围内,允许自由创建和再分发使用或依赖此基础设施(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 请求网络(高级 AI 集成与自主故障转移)
为了在将服务器负载降至最低的同时安全、可靠地运行,该模块配备了自主故障转移和速率限制系统(确保 AI 操作不会中断的机制)。
* **完全异步处理与串行队列 (Async Executor):**
所有对 AI 的 HTTP 请求均使用 `CompletableFuture` 和 Java 标准的 `HttpClient` 机制(异步 I/O 处理)执行,绝不阻塞 Minecraft 的 Tick。此外,“并发数始终最多为 1(队列管理)”,并实施了防止同时多次发送相同提示字符串的安全设计。
* **延迟评估重置 (Lazy Reset):**
对于模型“每日执行上限”和“每分钟执行上限”的初始化判定,不采用服务器的定期处理(持续监控),而是在下次请求发生时的时间戳比较中即时计算和重置,采用了“延迟评估(Lazy Reset)”机制,因此待机中的服务器负载为零。
* **密钥分散运用与分布式轮询 (Priority & Load Balancing):**
可以为同一提供商或模型注册多个 API 密钥。可以为每个模型(ModelEntry)设置优先级(`priority`: 数值越小优先级越高),当达到速率上限或发生错误时,系统会自动按优先级顺序回退(自动切换到其他模型或其他密钥)。
此外,**当存在多个具有相同优先级的模型时,系统将采用“轮询方式”分散目标地址,自动防止特定 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 存储系统(数据库功能)
这是让依赖模组极其轻松地保存和读取数据的基础设施。保存格式**严格固定为 JSON**。
* **类别的注册与层级管理:**
依赖模组(外部模组)在初始化时调用 `registerCategory("my_mod")`,即可自动生成与该类别名称关联的目录结构。“通用数据(Global)”和“玩家专属(UUID)数据”会自动分配到文件夹中保存。(※ 未预先注册类别就无法保存数据)。
* **内存缓存与动态解析:**
频繁访问的数据在读取时会作为 Map 缓存在内存中,随后的 `get` / `set` 操作无需进行磁盘访问(I/O),可即时处理。保存路径的根目录路径利用服务器启动事件(`ServerStartedEvent`)自动获取 `root/world/aidbwapi_core/` 等正确路径来确定。
* **同步即时保存机制:**
当对数据库进行写入(调用 `set()`)时,内存中的缓存更新的同时会**立即执行同步文件写入(刷新)**。(※ 仅错误日志输出使用后台每 3 小时的延迟计时器,但数据库本身不存在异步自动保存的延迟功能)。为确保安全,还实现了手动强制保存(`db save`)命令。
---
## ? 运行要求与安装 (Requirements & Setup)
* **Minecraft:** 1.21.1
* **Mod Loader:** NeoForge 21.1.219 及以上版本
* **Java:** Java 21 及以上版本
* **Side:** 服务器和客户端均必需
**安装:**
将本模组 (`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` 等)以及错误日志的定期刷新间隔(`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`)被中断式刷新,确保保存到磁盘。
---
## ?️ 命令参考 (Command Reference)
AI 的初始设置以及各种模型设置和管理均可通过游戏内命令轻松完成。
所有命令均以 `/dbwapi` 开头。(默认所需权限:`common.toml` 中记载的等级。初始值为 2)
* **参数与建议规范:** 在输入标识符(KeyName 或模型名称)时,所有已注册的配置都会在游戏中的 Tab 补全建议中显示。语法错误或参数不足将按 Brigadier 标准被拦截。
* **消息格式显示颜色:** 来自命令的反馈均以系统消息形式呈现,以 `[AiDb]`(绿色)开头,操作对象(数值或名称)以黄色高亮显示。错误和警告将以红色文本整体输出。
* **彻底保护 API 密钥等敏感信息的输出:** 在使用 `info` 或 `list` 等用于屏幕显示的命令导致 API 密钥信息输出到聊天栏时,出于保护目的,仅显示以下状态:“若原始密钥长度超过 5 个字符,则**仅显示前 4 个字符,其余所有字符均掩码为 `****`**”;“若原始密钥长度为 4 个字符或更少,则**作为例外,将所有字符全部掩码为 `****`**”。绝对不会在屏幕上输出明文密钥。此外,在输出系统日志等情况下,密钥也绝不会包含在内。
### ? 通用设置 (General & Config)
* `/dbwapi status` : 显示系统整体的运行概况。包括已加载的 KeyName 数量和模型数量,以及内存中处于等待处理队列(Queue)状态的 AI 错误和数据库错误的数量。
* `/dbwapi reload` : 强制重新加载 TOML 和 JSON(`keynames.json`)配置文件。进行手动文本编辑后请务必执行此命令。
* `/dbwapi version` : 显示本 Mod 的版本号。
* `/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(及其关联的所有模型配置组)才会被完全删除。
### ? 模型管理 (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` : 显示从依赖 Mod 等在 `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 基盘允许通过单例模式(`getInstance()`)或各种静态方法,从依赖 Mod(自制 Mod 等)的 Java 代码中调用并使用。请在 `build.gradle` 中将 `aidbwapi_core` 包含在依赖解析(`compileOnly` 等)中进行实现。
### 1. AI 异步请求 (`AiCoreAPI`)
内部已完全隐藏了速率限制检查、密钥分发、故障转移和异常处理管道。
对于调用方的开发者而言,只需“提交提示词字符串,并通过 CompletableFuture 接收结果字符串”,即可实现非常简洁的设计。
```java
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 的规范与类型:
本数据库并非能够直接保存和完全还原复杂类结构(POJO)的高级 ORM 工具。由于 Gson 等规范的限制,通过 get() 从 JSON 文件展开(还原)的数据都将作为 Map<String, Object>(或基本类型)的集合进行加载。
因此,虽然在保存时可以传递自定义类的实例,但在读取时必须假设需要从 Map 或标准类型中进行自行转换/重构(或通过单独的 Gson 反序列化)。这是一个极其简单的设计,建议仅使用简单的 Map、数值或基于字符串的类型。
import com.morwapi.aidbwapi_core.api.AiCoreAPI;
import com.morwapi.aidbwapi_core.api.CategoryDatabaseHandle;
import java.util.UUID;
// ------ Mod 初始化时 (FMLCommonSetupEvent 等) ------
// [1]. 类别的自动生成与注册
AiCoreAPI.getInstance().registerCategory("guild_mod");
```java
// [2]. 获取数据库操作句柄
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)的商业或非商业模组。
- English / 2. 日本語
AI DataBase wAPI Core (aidbwapi_core)
A core server-side mod for Minecraft 1.21.1 (NeoForge) that provides asynchronous request functionality to external AI (OpenAI-compatible LLM APIs) and a lightweight JSON-based persistent storage (database functionality).
This mod does not provide standalone features (such as chatbots) on its own; it is designed as a system infrastructure (Core) that allows other mods (dependent mods) to easily utilize advanced AI functions and data storage via the Java API (AiCoreAPI / DatabaseManager).
? Features & Architecture
1. AI Request Network (Advanced AI Integration & Autonomous Failover)
Equipped with an autonomous failover and rate-limiting system designed to ensure safe and reliable communication with external APIs while minimizing server load.
-
Full Async Processing & Serial Queues (Async Executor):
All HTTP requests to AI are executed using CompletableFuture and Java's standard HttpClient mechanism (asynchronous I/O), ensuring that Minecraft ticks are never blocked. Furthermore, it is designed for safety by ensuring the "number of concurrent executions is always at most one (queue management)," preventing multiple simultaneous transmissions of the same prompt string.
-
Lazy Evaluation Reset (Lazy Reset):
Initialization checks for "daily execution limits" and "per-minute execution limits" for models do not use periodic server tasks (constant monitoring). Instead, it adopts a Lazy Reset mechanism where calculations and resets are performed on-the-fly by comparing timestamps at the moment the next request occurs, resulting in zero standby server load.
-
Key Distribution & Distributed Round-Robin (Priority & Load Balancing):
Multiple API keys can be registered for the same provider or model. You can set a priority (priority: lower values indicate higher priority) for each ModelEntry. The system automatically falls back (switches to another model/key) to the next highest priority in the event of errors or rate limit exhaustion.
Additionally, if multiple models with the same priority exist, the system distributes the requests using a "Round-Robin" method, automatically preventing load concentration on a specific API key. This allows for safe operation by aggregating rate limit quotas from multiple free API keys.
-
Penalty Point (PP) System & Probabilistic Skipping (Penalty System):
When communication errors occur, the model is not immediately disabled. Instead, it is assigned Penalty Points (PP) based on the severity of the error, while a temporary cooldown is applied (Default: 429 = 60s, 5xx = 120s, Timeout = 60s, Connection Failure = 300s).
HTTP 429 (Rate Limited): +1 PP
HTTP 5xx (Server Error): +5 PP
Timeout / Connection / DNS Failure: +7 PP
- Successful Communication: Halves PP (
PP /= 2)
When selecting an execution candidate, models with PP are temporarily skipped with a probability calculated as:
$$\frac{PP}{PP + 4.0}$$
The system autonomously avoids or suppresses access to endpoints that are currently unstable by moving to the next candidate.
-
100-Round Fail-Safe Loop:
If all candidate models are currently in probabilistic skip or cooldown, the system loops back to the beginning of the candidate list for a re-draw. To prevent infinite loops, a robust fail-safe terminates the process after a maximum of 100 rounds, either selecting the highest priority available model (lowest priority value) as a compromise or returning a complete failure to the API layer.
-
Exception Handling (HTTP 400 Bad Request):
If a configuration-related error occurs, such as HTTP 401 (Unauthorized) or HTTP 404 (Model Not Found), the specific model is automatically disabled (disabled) and the system immediately falls back (retries) to the next candidate. However, for HTTP 400 (Bad Request), since the issue is likely a bug specific to the prompt or data structure, switching models is unlikely to succeed. Therefore, the system returns an error immediately to the calling dependent mod without failing over (instant termination of useless loops).
2. JSON Storage System (Database Functionality)
A foundation that allows dependent mods to save and load their own data with extreme ease. The storage format is strictly fixed to JSON.
- Category Registration & Hierarchical Management:
By calling
registerCategory("my_mod") during initialization, dependent mods (external mods) automatically generate a directory structure linked to that category name. Data is automatically sorted into "General Data (Global)" and "Individual Player (UUID) Data" folders. (Note: Data cannot be saved without prior registration).
- Memory Caching & Dynamic Resolution:
Frequently accessed data is cached as a Map in memory upon loading. Subsequent
get/set operations are processed immediately without disk I/O. The root path for the storage directory is automatically determined by retrieving the correct path (e.g., root/world/aidbwapi_core/) during the ServerStartedEvent.
- Synchronous & Immediate Save Mechanism:
When a write operation (
set()) is performed on the database, the memory cache is updated and an immediate synchronous file write (flush) is executed. (Note: While error logs use a background delay timer every 3 hours, the DB itself does not have an asynchronous auto-save delay feature). For safety, a manual force-save command (db save) is also implemented.
? Requirements & Setup
- Minecraft: 1.21.1
- Mod Loader: NeoForge 21.1.219 or later
- Java: Java 21 or higher
- Side: Required on both Server and Client
Installation:
Place this mod (aidbwapi_core-x.x.x.jar) into the mods folder of your server or client and launch.
⚙️ Configuration & Directory Structure
All settings, databases, and error logs are deployed in the server root directory or under saves/[world_name]/ for clients.
config/aidbwapi_core-common.toml: Basic operational settings for the entire mod.
commandPermissionLevel: Required OP level for all /dbwapi commands (Default: 2). Can be changed from 0 to 4.
requestTimeoutSeconds: Timeout for AI communication responses (Default: 60 seconds).
penaltyCurveFactor: Adjustment factor for the PP skip probability curve (Default: 4.0).
- Other settings include cooldown seconds for various HTTP errors (
rateLimitSeconds, etc.) and the periodic flush interval for error logs (flushIntervalMinutes). Some basic settings can be changed and persisted instantly via in-game commands.
config/aidbwapi_core-keynames.json: Stores AI endpoint URLs, API keys in plain text, model lists, and various rate limit settings (dailyLimit, minuteLimit) in a structured format.
- ⚠️ [IMPORTANT] API Key Security & Registration Method
As a specification of this mod, API keys are not encrypted and are saved as plain text within this JSON file. While keys can be registered via in-game commands (
/dbwapi keyname setkey), due to Minecraft's specifications, the full command you type into the chat (the plain text API key string) will be recorded as-is in the server's logs/latest.log and console log files.
To ensure security, avoid in-game command entry. Instead, we strongly recommend opening this file directly with a text editor, editing/saving the "apiKey": "sk-xxxx..." field, and then running the /dbwapi reload command in-game to reload the settings.
[World Save Root]/aidbwapi_core/[category_name]/: The root for settings and data storage for each category saved and cached via CategoryDatabaseHandle, etc.
global.json for general data and a players/ folder containing <UUID>.json files for individual players are placed directly under the category.
[World Save Root]/aidbwapi_core/log/: The destination where the error history (debug logs) of AI and DB processing accumulated in memory is exported in JSON format in the background.
- A maximum of
20 files are kept for the latest error logs by default, with older files being automatically rotated (deleted).
- Any unsaved error states remaining in memory are flushed during server shutdown/termination (
ServerStoppingEvent) to ensure they are saved to disk.
?️ Command Reference
Initial AI setup and various model settings/management can be easily performed via in-game commands.
All commands start with /dbwapi.
- Arguments & Suggestions: When entering identifiers (KeyName or Model name), suggestions (Tab completion) will be displayed for all registered settings in-game. Syntax errors or insufficient arguments will be rejected as per Brigadier standards.
- Message Format Colors: All feedback from commands starts with
[AiDb] (Green). The target of the operation (values or names) is highlighted in Yellow. Errors and warnings are output in Red text.
- Strict Output Protection for API Keys: When API key information is output to the chat via display commands (
info or list), it is masked for protection: "If the original key is 5 characters or longer, only the first 4 characters are displayed, and all remaining characters are masked with ****." "If the key is 4 characters or fewer, all characters are masked with **** as an exception." Raw keys are never output to the screen or logs.
? General & Config
/dbwapi status: Summary of system operation. Displays the number of loaded KeyNames and Models, as well as the count of AI and DB errors currently queued in memory for output.
/dbwapi reload: Force reloads the TOML and JSON (keynames.json) configuration files. Always run this after manual text editing.
/dbwapi version: Displays the version of this mod.
/dbwapi config show: Displays the currently applied debug log settings (debugLogging) and AI communication timeout (requestTimeoutSeconds).
/dbwapi config debug true|false: Instantly toggles the debug level (detailed log output) on/off and persists the setting.
/dbwapi config timeout <seconds>: Changes and persists the AI communication timeout (basic setting).
? KeyName Management
Centralized management of the set consisting of the URL (provider endpoint) and API key as a system-wide "Registered Name (keyName)."
/dbwapi keyname list / info <keyName>: Displays a list of all registered KeyNames or details for a specific KeyName. (API keys are masked).
/dbwapi keyname add <keyName> <apiUrl> <apiKey>: Registers a connection info set for a new AI provider (OpenAI-compatible). ※ While duplicate registered names (keyName) are errors, registering the same apiUrl and apiKey under different names is permitted (for load balancing).
/dbwapi keyname seturl <keyName> <apiUrl>: Updates only the API endpoint URL of an existing KeyName.
/dbwapi keyname setkey <keyName> <apiKey>: Updates the API key of an existing KeyName. (※ Warning: Risk of log exposure. Direct JSON editing is recommended for safety.)
/dbwapi keyname remove <keyName> [confirm]: Safety-locked deletion. Requires true at the end to execute.
? Model & Failover Management
Model identifiers are always specified as <keyName>.<model_name> (e.g., taro_groq.llama-3-70b).
/dbwapi model list / info <keyName>.<model_name>: Displays the operational status of all models (priority, penalty/PP status, current status, etc.) and detailed limit metrics for individual models.
/dbwapi model add <keyName>.<model_name> [dailyLimit] [minuteLimit]: Adds a new available model to the parent KeyName. Use -1 for unlimited.
/dbwapi model move <keyName>.<model_name> up|down: Moves/swaps the priority of a specified model one level up (up) or one level down (down).
/dbwapi model limit <keyName>.<model_name> daily|minute <value>: Changes the maximum limits for a model (-1 for unlimited). Changes are applied immediately.
/dbwapi model enable <keyName>.<model_name> / disable <keyName>.<model_name>: Enables or temporarily disables the lottery setting for a specific model.
- [Recovery from Auto-Disable]: If an endpoint configuration issue occurs (e.g.,
HTTP 401/403 Invalid API Key or HTTP 404 Not Found), the system will automatically force the model to be disabled (disabled). After resolving the mismatch (e.g., via seturl), manually restore it using this enable command.
/dbwapi model reset <keyName>.<model_name>: Instantly resets the accumulated PP (penalty) and cooldown status of the target model to zero.
/dbwapi model resetall: Resets "all models" currently registered at once.
/dbwapi model remove <keyName>.<model_name> [confirm]: Deletes the specified model. (※ Safety lock required; true at the end is mandatory).
? AI Test, Error Logs, & DB Management (Tests & Logger)
/dbwapi ai status: Displays the number of AI requests currently being processed (Active) and those in the asynchronous processing wait queue (Queue).
/dbwapi ai test: Uses the "currently valid model" to send a short test prompt and check if a text response actually returns.
/dbwapi ai errors [count]: Outputs a history of recent AI communication errors (up to 50 entries, default 10).
/dbwapi ai errors clear: Clears the error history memory for display.
/dbwapi db list: Displays a list of all category names currently registered in the DatabaseManager.
/dbwapi db info <category>: Displays metrics such as the storage root path, global DB key count, and current player UUID cache count.
/dbwapi db errors [count] / db errors clear: Same as ai errors but for DB-specific logs (e.g., FILE_WRITE_ERROR).
/dbwapi db save: Explicitly forces a file write (flush) of all changes in all databases in memory.
? For Developers: Java API Implementation (API Layer for Developers)
The Core infrastructure is utilized by calling it via the singleton (getInstance()) or various static methods from the Java code of your dependent mod. Please include aidbwapi_core as a dependency (e.g., compileOnly) in your build.gradle before implementing.
1. Asynchronous Request to AI (AiCoreAPI)
All internal rate-limit checks, key distribution, failovers, and exception handling pipelines are hidden.
import com.morwapi.aidbwapi_core.api.AiCoreAPI;
// Execution results are returned asynchronously as CompletableFuture<String>.
AiCoreAPI.getInstance().requestAI("Tell me the appeal of Minecraft in 100 characters")
.thenAccept(response -> {
// [On Success] Process the AI response string (response).
System.out.println("AI Response: " + response);
// ⚠️ [CAUTION] This is executed in a "Separate Thread (inside AsyncExecutor)".
// To safely access the Minecraft world (sending chat, placing blocks, entity operations, etc.),
// you must ensure the processing is returned to the main thread (Server Thread)
// using a task queue like server.execute(() -> { ... }).
})
.exceptionally(ex -> {
// [On Failure/Exception] Reached if all models are unavailable,
// retry limit (100) exceeded, or request parameters are invalid (HTTP 400).
System.out.println("AI Communication Error: " + ex.getMessage());
return null; // CompletableFuture requirement
});
### 2. JSON Database and Categories (`CategoryDatabaseHandle`)
Register and obtain categories via `AiCoreAPI`, and receive handles for `PlayerDatabase` or `GlobalDatabase` to save and read data.
**[IMPORTANT] JsonStorageEngine Specifications and Types:**
This database is not a high-performance ORM tool for directly saving and fully restoring complex custom class structures (POJOs). Due to GSON specifications, all data restored from JSON files via `get()` is loaded as collections of **`Map<String, Object>`** (or primitive types).
Therefore, while you can pass custom class instances when saving, the design is extremely simple and assumes you will cast or reconstruct them from Maps or standard types (or deserialize separately with GSON) when reading. Use with simple Maps, numbers, or strings is recommended.
import com.morwapi.aidbwapi_core.api.AiCoreAPI;
import com.morwapi.aidbwapi_core.api.CategoryDatabaseHandle;
import java.util.UUID;
// ------ During Mod Initialization (e.g., FMLCommonSetupEvent) ------
// [1]. Automatic generation and registration of categories
AiCoreAPI.getInstance().registerCategory("guild_mod");
// [2]. Obtaining a DB handle for operation
CategoryDatabaseHandle dbHandle = AiCoreAPI.getInstance().getCategoryDatabase("guild_mod");
// ------ Implementation Example (e.g., PlayerJoinEvent) ------
UUID playerId = player.getUUID();
// [1]. Loading data (Read)
// Restored from JSON as Map format, etc. Returns null if not created.
Object rawData = dbHandle.getPlayerDB().get(playerId, "killCount");
int killCount = 0;
if (rawData != null) {
// Since numbers may become Double due to GSON, receive as Number type and cast.
killCount = ((Number) rawData).intValue();
}
// [2]. Updating and saving data (Save)
killCount += 1;
// Arguments: Player UUID, storage identification key name, value to save (Object)
dbHandle.getPlayerDB().set(playerId, "killCount", killCount);
// ※ The moment this `set()` method is called, the file is written [synchronously and immediately]
// to `guild_mod/players/<UUID>.json` at the same time it is applied to the memory (cache-side Map).
## ⚖️ License (License)
The source code and provided binaries of this mod are provided and published under the **Apache License, Version 2.0**.
Creation and redistribution of commercial or non-commercial mods that use or depend on this infrastructure (API) are permitted freely within the scope of the license terms.
# AI DataBase wAPI Core (aidbwapi_core)
Minecraft 1.21.1 (NeoForge) 向けに、外部AI(OpenAI互換LLM API)への非同期リクエスト機能、およびJSONベースの軽量な永続化ストレージ(データベース機能)を提供するコア・サーバーサイドModです。
本Mod単体で完結する機能(チャットボット等)は持たず、他のMod(依存Mod)が高度なAI機能やデータ保存機能を Java API(`AiCoreAPI` / `DatabaseManager`) として簡単に利用できるように設計された**システム基盤(Core)**です。
---
## ? コア機能とアーキテクチャ (Features & Architecture)
### 1. AI Request Network (高度なAI連携と自律型フェイルオーバー)
外部APIへの通信を、サーバー負荷を極限まで抑えつつ安全・確実に運用するための自律型フェイルオーバー・レートリミットシステム(AI動作を止めない仕組み)を備えています。
* **完全非同期処理と直列キュー (Async Executor):**
AIへのHTTPリクエストはすべて `CompletableFuture` とJava標準の `HttpClient` 機構(非同期I/O処理)を用いて実行され、MinecraftのTickを一切ブロックしません。また「同時実行数は常に最大1つまで(キュー管理)」とし、同一のプロンプト文字列を複数同時に多重送信しない安全設計が施されています。
* **遅延評価リセット (Lazy Reset):**
モデルの「1日あたりの実行上限」「1分あたりの実行上限」の初期化判定は、サーバーの定期処理(常時監視)を行わず、次回リクエストが発生した瞬間のタイムスタンプ比較で都度計算・リセットする「遅延評価(Lazy Reset)」メカニズムを採用しており、待機中のサーバー負荷はゼロです。
* **キーの分散運用と分散ラウンドロビン (Priority & Load Balancing):**
同一のプロバイダやモデルに対して、複数のAPIキーを登録できます。モデル(ModelEntry)ごとに優先度(`priority`: 数値が小さいほど高優先)を設定でき、レート上限到達時やエラー時には優先度の高い順へ自動でフォールバック(別モデル・別キーへの自動切替)を行います。
さらに、**同率優先度のモデルが複数存在する場合、システムは「ラウンドロビン方式」で行き先を分散させ、特定の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`(リクエスト不正)に関しては「プロンプトや送信データの構造そのものにバグがある」ため、どのモデルに切り替えても失敗する可能性が高く、フェイルオーバーさせずに即座に呼び出し元の依存Mod側へエラーを返却します(無駄なループの即時打ち切り)。
### 2. JSON Storage System (データベース機能)
依存Modが独自のデータを極めて簡単に保存・読み出しできる基盤です。保存フォーマットは**JSON完全固定**です。
* **カテゴリの登録と階層管理:**
依存Mod(外部Mod)が初期化時などに `registerCategory("my_mod")` を呼ぶことで、そのカテゴリ名に紐づくディレクトリ構成が自動生成されます。「汎用データ(Global)」と「プレイヤー個別(UUID)データ」は自動でフォルダが振り分けられ保存されます。(※事前登録を行わずにデータを保存することはできません)。
* **メモリキャッシュと動的解決:**
頻繁にアクセスされるデータは、読み込み時にメモリ上にMapとしてキャッシュされ、以後の `get` / `set` はディスクアクセス(I/O)を行わず即座に処理されます。保存先ディレクトリのルートパスは、サーバー起動時イベント(`ServerStartedEvent`)を利用して `root/world/aidbwapi_core/` 等の正しいパスを自動取得して決定します。
* **同期的・即時セーブ機構:**
データベースに対する書き込み(`set()` の呼び出し)が行われると、メモリ上のキャッシュが更新されるのと同時に**即座に同期的ファイル書き出し(フラッシュ)**が実行されます。(※エラーログ出力のみはバックグラウンドの3時間ごとの遅延タイマーを使用しますが、DB自体に非同期オートセーブの遅延機能は存在しません)。安全のため、手動での強制保存(`db save`)コマンドも実装されています。
---
## ? 動作要件とインストール (Requirements & Setup)
* **Minecraft:** 1.21.1
* **Mod Loader:** NeoForge 21.1.219 以降
* **Java:** Java 21 以上
* **サイド:** サーバー・クライアント両方必須
**インストール:**
当Mod (`aidbwapi_core-x.x.x.jar`) をサーバーまたはクライアントの `mods` フォルダに配置して起動します。
---
## ⚙️ 設定ファイルとディレクトリ構造 (Configuration)
すべての設定やデータベース・エラーログは、サーバーのルートディレクトリ、またはクライアントの `saves/[ワールド名]/` 配下に展開されます。
* **`config/aidbwapi_core-common.toml`** : Mod全体の基礎動作設定ファイル。
* `commandPermissionLevel`: 全ての `/dbwapi` コマンドの要求OP権限レベル(デフォルト `2`)。0〜4に変更可能です。
* `requestTimeoutSeconds`: AI通信の応答タイムアウト秒数(デフォルト `60`秒)。
* `penaltyCurveFactor`: PPスキップ確率計算曲線の調整係数(デフォルト `4.0`)。
* 他、各種HTTPエラー時のクールダウン秒数(`rateLimitSeconds` 等)や、エラーログの定期フラッシュ間隔(`flushIntervalMinutes`)等を設定可能。一部の基礎設定はインゲームコマンド(`/dbwapi config ...` 等)からでも即座に変更・永続化されます。
* **`config/aidbwapi_core-keynames.json`** : AIエンドポイントURL、APIキーの平文、およびモデル一覧と各種レート制限(`dailyLimit`, `minuteLimit`)の設定が構造化保存されます。
* **⚠️【重要】APIキーのセキュリティ・登録方法について**
Modの仕様としてAPIキー自体は暗号化されず、このJSONファイル内に平文で保存されます(`.gitignore` 等での防衛やOSサーバー権限による保護運用を前提としています)。インゲームのコマンド(`/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`)に割り込みでフラッシュされ、確実にディスクへ救済・保存されます。
---
## ?️ コマンドリファレンス (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` : 当Modのバージョンを表示します。
* `/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順位)を、1つ上(`up`)または 1つ下(`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` : 依存Mod等から `DatabaseManager` に現在登録されている全カテゴリ名の一覧を表示します。
* `/dbwapi db info <カテゴリ名>` : 対象カテゴリの保存先ルートパス、グローバルDBのキー数(ロード済の規模感)、および現在キャッシュに乗っているプレイヤー毎のUUIDデータの総数などのメトリクスを表示します。
* `/dbwapi db errors [件数]` / `db errors clear` : `ai errors` と同じ仕組みで、DB特有のログ(`FILE_WRITE_ERROR` 等)をチャットに出力(省略時はデフォルト10件)・クリアします。
* `/dbwapi db save` : メモリ上の全データベースの変更内容を明示的に強制ファイル書き出し(フラッシュ)させます。(※通常は `set` 時に自動で即時同期保存されるため、直接メモリを改ざんした場合の救済用です)。
---
## ? 開発者向け: Java APIの実装利用方法 (API Layer for Developers)
当Core基盤は、依存Mod(自作Mod等)の Java コードから、シングルトン(`getInstance()`)または各種 Static メソッド経由で呼び出して利用します。`build.gradle` で `aidbwapi_core` を依存解決(`compileOnly` 等)に含めた上で実装してください。
### 1. AIへの非同期リクエスト (`AiCoreAPI`)
内部でのレート制限チェック、キーの振り分け、フォールバック、例外ハンドリングパイプラインをすべて隠蔽しています。
呼び出し側の開発者は「プロンプト文字列を投げて、CompletableFuture で結果の文字列を受け取る」だけで完結する非常にシンプルな設計として機能します。
```java
import com.morwapi.aidbwapi_core.api.AiCoreAPI;
// CompletableFuture<String> として実行結果が非同期に返却されます。
AiCoreAPI.getInstance().requestAI("Minecraftの魅力を100文字で教えて")
.thenAccept(response -> {
// [成功時想定] AIのレスポンス文字列(response)を取得して処理。
System.out.println("AIの回答: " + response);
// ⚠️【注意】ここは「別スレッド(AsyncExecutor内部)」で実行されています。
// マイクラの世界(チャット送信、ブロック設置、エンティティ操作等)へ安全にアクセスするためには、
// 必ず 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;
// ------ Modの初期化時 (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)
このModのソースコードおよび提供されるバイナリは Apache License, Version 2.0 で提供・公開されています。
本基盤(API)を利用・依存した商用・非商用Modの作成および再配布は、ライセンス条項の範囲内で自由に行っていただけます。
评论 0
登录后参与评分
还没有评论,来抢沙发吧