AI Model Hub API 使用文档
为 Halo 插件提供统一的 AI 模型调用能力，支持文本对话和图像生成。
目录
快速开始
第一步：添加依赖
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.acanyo:plugin-aimodel-hub:1.0.0-SNAPSHOT'
}
第二步：声明插件依赖
在 plugin.yaml 中：
spec:
pluginDependencies:
aimodel-hub: ">=1.0.0"
第三步：开始使用
import static com.xhhao.aimodelhub.api.ChatModels.*;
import static com.xhhao.aimodelhub.api.ImageModels.*;
import com.xhhao.aimodelhub.api.ChatModels.Provider;
// 文本对话
ChatModels.chat("你好").subscribe(System.out::println);
// 图像生成
ImageModels.generate("一只可爱的猫").subscribe(urls -> urls.forEach(System.out::println));
文本对话 API
使用 ChatModels 静态类调用文本对话。
import static com.xhhao.aimodelhub.api.ChatModels.*;
import com.xhhao.aimodelhub.api.ChatModels.Provider;
import com.xhhao.aimodelhub.api.ChatOptions;
import com.xhhao.aimodelhub.api.ChatMessage;
方法一览
基础用法
// 1. 最简单 - 使用默认供应商和全局配置
chat("你好").subscribe(System.out::println);
// 2. 指定供应商
chat(Provider.OPENAI, "你好").subscribe(System.out::println);
chat(Provider.ZHIPU, "你好").subscribe(System.out::println);
chat(Provider.SILICONFLOW, "你好").subscribe(System.out::println);
// 3. 自定义 API Key（不需要 ChatOptions）
chat(Provider.OPENAI, "sk-xxx", "gpt-4o", "你好").subscribe(System.out::println);
// 4. 完整配置（需要调参时）
ChatOptions options = ChatOptions.builder()
.apiKey("sk-xxx")
.model("gpt-4o")
.temperature(0.7)
.maxTokens(2000)
.build();
chat(Provider.OPENAI, options, "你好").subscribe(System.out::println);
流式输出
// 基础流式
chatStream("写一篇文章").subscribe(System.out::print);
// 指定供应商
chatStream(Provider.OPENAI, "写一首诗").subscribe(System.out::print);
// 自定义 API Key
chatStream(Provider.OPENAI, "sk-xxx", "gpt-4o", "写一首诗").subscribe(System.out::print);
// 完整配置
chatStream(Provider.OPENAI, options, "写一首诗").subscribe(System.out::print);
多轮对话
List<ChatMessage> messages = List.of(
ChatMessage.system("你是一个 Java 编程助手"),
ChatMessage.user("什么是 Spring Boot?"),
ChatMessage.assistant("Spring Boot 是一个快速开发框架..."),
ChatMessage.user("如何创建项目?")
);
chat(messages).subscribe(System.out::println);
chat(Provider.OPENAI, messages).subscribe(System.out::println);
chatStream(messages).subscribe(System.out::print);
记忆对话
// 自动管理上下文
ChatModels.withMemory("你是编程助手")
.flatMap(model -> model.chat("我叫张三"))
.subscribe(System.out::println);
// 指定供应商
ChatModels.withMemory(Provider.OPENAI, "你是翻译助手")
.flatMap(model -> model.chat("翻译：Hello"));
图像生成 API
使用 ImageModels 静态类生成图像。
import static com.xhhao.aimodelhub.api.ImageModels.*;
import com.xhhao.aimodelhub.api.ImageModels.Provider;
import com.xhhao.aimodelhub.api.ImageOptions;
图像方法一览
图像基础用法
// 1. 最简单
generate("一只可爱的猫").subscribe(urls -> urls.forEach(System.out::println));
// 2. 指定供应商
generate(Provider.OPENAI, "未来城市").subscribe(urls -> ...);
generate(Provider.ZHIPU, "山水画").subscribe(urls -> ...);
generate(Provider.SILICONFLOW, "风景照片").subscribe(urls -> ...);
// 3. 自定义 API Key
generate(Provider.OPENAI, "sk-xxx", "dall-e-3", "一只猫").subscribe(urls -> ...);
// 4. 完整配置
ImageOptions options = ImageOptions.builder()
.apiKey("sk-xxx")
.model("dall-e-3")
.size("1024x1792")
.quality("hd")
.style("vivid")
.build();
generate(Provider.OPENAI, options, "印象派日落").subscribe(urls -> ...);
硅基流动特有参数
ImageOptions options = ImageOptions.builder()
.apiKey("sk-your-api-key")
.model("black-forest-labs/FLUX.1-schnell")
.size("1024x1024")
.steps(20) // 采样步数
.guidanceScale(7) // 引导系数
.seed(12345L) // 随机种子
.negativePrompt("低质量, 模糊, 变形") // 负面提示词
.build();
generate(Provider.SILICONFLOW, options, "高质量的风景照片")
.subscribe(urls -> urls.forEach(System.out::println));
ChatOptions 参数详解
ChatOptions 用于配置文本对话模型的所有参数：
ChatOptions options = ChatOptions.builder()
// ==================== 基础参数 ====================
.apiKey("sk-xxx") // API Key（自定义调用时必填）
.model("gpt-4o") // 模型名称
.baseUrl("https://...") // 自定义 API 地址（兼容 OpenAI 格式的服务）
// ==================== 生成参数 ====================
.temperature(0.7) // 温度 0-2，越高越随机创意，越低越确定
.topP(0.9) // 核采样 0-1，与 temperature 二选一调整
.maxTokens(2000) // 最大生成 Token 数
.frequencyPenalty(0.0) // 频率惩罚 -2~2，减少重复词
.presencePenalty(0.0) // 存在惩罚 -2~2，鼓励新话题
.stop(List.of("END", "###")) // 停止词列表
.seed(12345) // 随机种子，相同种子产生相同输出
.user("user-123") // 用户标识，用于追踪
// ==================== 网络参数 ====================
.timeout(Duration.ofSeconds(60)) // 请求超时时间
.maxRetries(3) // 最大重试次数
.customHeaders(Map.of( // 自定义请求头
"X-Custom-Header", "value"
))
// ==================== OpenAI 特有 ====================
.organizationId("org-xxx") // OpenAI 组织 ID
.projectId("proj-xxx") // OpenAI 项目 ID
.maxCompletionTokens(1000) // o1 系列模型的最大完成 Token
.logitBias(Map.of(50256, -100)) // Token 偏置
.responseFormat("json_object") // 响应格式: text/json_object/json_schema
.strictJsonSchema(true) // 严格 JSON Schema 模式
.parallelToolCalls(true) // 是否并行调用工具
.strictTools(true) // 严格工具模式
// ==================== 硅基流动特有 ====================
.enableThinking(true) // 开启思维模式（推理模型如 DeepSeek-R1）
.thinkingBudget(4096) // 思维链 Token 预算 128-32768
.minP(0.1) // 动态过滤阈值 0-1（Qwen3 模型）
.topK(50) // Top-K 采样
.repetitionPenalty(1.1) // 重复惩罚
.n(1) // 生成数量
// ==================== 智谱特有 ====================
.requestId("req-xxx") // 请求追踪 ID
.webSearch(true) // 联网搜索（GLM-4 支持）
.toolChoice("auto") // 工具选择: auto/none/required
// ==================== 调试 ====================
.logRequests(true) // 记录请求日志
.logResponses(true) // 记录响应日志
.build();
参数说明表
快捷方法
// 快速创建
ChatOptions options = ChatOptions.of("sk-xxx", "gpt-4o");
// 包含 baseUrl
ChatOptions options = ChatOptions.of("sk-xxx", "https://api.example.com", "model-name");
ImageOptions 参数详解
ImageOptions 用于配置图像生成模型的所有参数：
ImageOptions options = ImageOptions.builder()
// ==================== 基础参数 ====================
.apiKey("sk-xxx") // API Key
.model("dall-e-3") // 模型名称
.baseUrl("https://...") // 自定义 API 地址
// ==================== 生成参数 ====================
.size("1024x1024") // 图片尺寸
.quality("hd") // 质量: standard/hd (DALL-E 3)
.n(1) // 生成数量 (DALL-E 3 只支持 1)
.style("vivid") // 风格: vivid/natural (DALL-E 3)
.watermark(false) // 是否加水印
// ==================== 网络参数 ====================
.timeout(Duration.ofSeconds(120)) // 超时时间（图像生成较慢）
.maxRetries(2) // 最大重试次数
// ==================== 硅基流动特有 ====================
.steps(20) // 采样步数 1-50
.guidanceScale(7) // 引导系数 1-20
.seed(12345L) // 随机种子
.negativePrompt("低质量") // 负面提示词
.imageFormat("png") // 输出格式: png/jpeg
.build();
支持的图片尺寸
支持的供应商和模型
文本对话模型
图像生成模型
错误处理
chat(Provider.OPENAI, "你好")
.onErrorResume(e -> {
if (e instanceof AiModelException) {
AiModelException aiError = (AiModelException) e;
System.err.println("AI 错误: " + aiError.getMessage());
}
return Mono.just("抱歉，AI 服务暂时不可用");
})
.subscribe(System.out::println);
常见错误
最佳实践
1. 合理设置 Temperature
// 代码生成：低温度，确定性高
ChatOptions codeOptions = ChatOptions.builder()
.apiKey("sk-xxx")
.temperature(0.2)
.build();
chat(Provider.OPENAI, codeOptions, "写一个快速排序").subscribe(System.out::println);
// 创意写作：高温度，更有创意
ChatOptions creativeOptions = ChatOptions.builder()
.apiKey("sk-xxx")
.temperature(0.9)
.build();
chat(Provider.OPENAI, creativeOptions, "写一首诗").subscribe(System.out::println);
2. 使用系统提示定义角色
List<ChatMessage> messages = List.of(
ChatMessage.system("""
你是一个专业的技术文档编写助手。
规则：
1. 使用清晰简洁的语言
2. 提供代码示例
3. 使用 Markdown 格式
"""),
ChatMessage.user(userQuestion)
);
chat(messages).subscribe(System.out::println);
3. 流式输出提升用户体验
// 在 Web 应用中使用 SSE 推送
@GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamChat(@RequestParam String message) {
return ChatModels.chatStream(Provider.OPENAI, message);
}
4. 记忆对话
// 使用 withMemory 自动管理上下文
ChatModels.withMemory("你是一个专业的编程助手")
.flatMap(model -> model.chat("你好"))
.subscribe(System.out::println);
5. 错误重试策略
chat(Provider.OPENAI, "你好")
.retryWhen(Retry.backoff(3, Duration.ofSeconds(1))
.filter(e -> e instanceof TimeoutException))
.subscribe(System.out::println);
日志记录
所有通过 ChatModels 和 ImageModels 的调用都会自动记录日志，包括：
调用者插件名称
模型供应商和名称
Token 使用量（输入/输出/总计）
调用耗时
成功/失败状态
错误信息
在 Halo 后台 "工具" → "AI 调用日志" 中查看统计和详情。