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;

方法一览

方法	说明
`chat(message)`	使用默认供应商对话
`chat(Provider, message)`	指定供应商对话
`chat(Provider, apiKey, model, message)`	自定义 API Key 对话
`chat(Provider, options, message)`	完整配置对话
`chatStream(...)`	流式输出（参数同上）
`chat(messages)`	多轮对话
`withMemory(systemPrompt)`	带记忆的对话

基础用法

// 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;

图像方法一览

方法	说明
`generate(prompt)`	使用默认供应商生成
`generate(Provider, prompt)`	指定供应商生成
`generate(Provider, apiKey, model, prompt)`	自定义 API Key
`generate(Provider, options, prompt)`	完整配置生成

图像基础用法

// 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();

参数说明表

参数	类型	范围	说明
`temperature`	Double	0-2	控制随机性，0=确定性，2=最随机
`topP`	Double	0-1	核采样，只考虑概率累计达到 P 的 Token
`maxTokens`	Integer	1-128000	最大生成 Token 数，不同模型上限不同
`frequencyPenalty`	Double	-2~2	减少已出现词的频率
`presencePenalty`	Double	-2~2	鼓励生成新的话题
`seed`	Integer	-	固定随机种子，实现可复现输出
`timeout`	Duration	-	请求超时时间
`maxRetries`	Integer	0-10	失败重试次数

快捷方法

// 快速创建
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();

支持的图片尺寸

供应商	模型	支持的尺寸
OpenAI	dall-e-2	256x256, 512x512, 1024x1024
OpenAI	dall-e-3	1024x1024, 1024x1792, 1792x1024
智谱	cogview-3	1024x1024, 768x1024, 1024x768
硅基流动	FLUX 系列	自定义，如 1024x1024

支持的供应商和模型

文本对话模型

供应商	Provider 枚举	默认模型	推荐模型
OpenAI	`Provider.OPENAI`	gpt-4o-mini	gpt-4o, gpt-4o-mini, gpt-4-turbo, o1-preview
智谱 AI	`Provider.ZHIPU`	glm-4-flash	glm-4, glm-4-flash, glm-4-plus
硅基流动	`Provider.SILICONFLOW`	Qwen/Qwen3-8B	Qwen 系列, DeepSeek 系列

图像生成模型

供应商	Provider	默认模型	推荐模型
OpenAI	`Provider.OPENAI`	dall-e-3	dall-e-2, dall-e-3
智谱 AI	`Provider.ZHIPU`	cogview-3-flash	cogview-3, cogview-3-flash
硅基流动	`Provider.SILICONFLOW`	FLUX.1-schnell	FLUX.1-schnell, FLUX.1-dev, Stable Diffusion

错误处理

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);

常见错误

错误	原因	解决方案
API Key 未配置	插件设置中未填写 API Key	在 Halo 后台配置
请求超时	网络问题或模型响应慢	增加 timeout 配置
Token 超限	输入+输出超过模型限制	减少输入或 maxTokens
余额不足	API 账户余额用尽	充值或更换 API Key

最佳实践

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 调用日志" 中查看统计和详情。

#AI Model Hub API 使用文档

#目录

#快速开始

#第一步：添加依赖

#第二步：声明插件依赖

#第三步：开始使用

#文本对话 API

#方法一览

#基础用法

#流式输出

#多轮对话

#记忆对话

#图像生成 API

#图像方法一览

#图像基础用法

#硅基流动特有参数

#ChatOptions 参数详解

#参数说明表

#快捷方法

#ImageOptions 参数详解

#支持的图片尺寸

#支持的供应商和模型

#文本对话模型

#图像生成模型

#错误处理

#常见错误

#最佳实践

#1. 合理设置 Temperature

#2. 使用系统提示定义角色

#3. 流式输出提升用户体验

#4. 记忆对话

#5. 错误重试策略

#日志记录