Solon-AI请求构建：标准化请求参数封装
项目地址: https://gitcode.com/opensolon/solon-ai 还在为不同AI服务商的API参数差异而头疼？Solon-AI通过标准化的请求参数封装，让开发者用一套统一的接口对接多种AI服务，大幅降低集成复杂度。本文将深入解析Solon-AI的请求构建机制，助你掌握标准化参数封装的精髓。
请求构建的核心架构
Solon-AI采用分层设计，将请求构建过程抽象为三个核心层次：
核心请求类：ChatRequest
ChatRequest 是请求构建的入口点，封装了所有必要的请求参数：
public class ChatRequest {
private final ChatConfig config; // 配置信息
private final ChatDialect dialect; // 方言处理器
private final ChatOptions options; // 请求选项
private final boolean stream; // 是否为流式请求
private List<ChatMessage> messages; // 消息列表
public String toRequestData() {
// 调用方言构建具体的JSON请求
return dialect.buildRequestJson(config, options, messages, stream);
}
}
标准化选项配置：ChatOptions
ChatOptions 提供了统一的参数配置接口，支持各种AI服务的通用参数：
public class ChatOptions {
// 常用选项常量定义
public static final String MAX_TOKENS = "max_tokens";
public static final String TEMPERATURE = "temperature";
public static final String TOP_P = "top_p";
private final Map<String, FunctionTool> tools = new LinkedHashMap<>();
private final Map<String, Object> toolsContext = new LinkedHashMap<>();
private final Map<String, Object> options = new LinkedHashMap<>();
// 工具配置方法
public ChatOptions toolsAdd(FunctionTool tool) {
tools.put(tool.name(), tool);
return this;
}
// 通用参数配置
public ChatOptions max_tokens(long max_tokens) {
return optionAdd(MAX_TOKENS, max_tokens);
}
public ChatOptions temperature(float temperature) {
return optionAdd(TEMPERATURE, temperature);
}
}
参数封装的实现原理
1. 消息构建标准化
Solon-AI支持多种消息类型，每种类型都有标准化的构建方式：
// 系统消息构建
protected void buildChatMessageNodeDo(ONode oNode, SystemMessage msg) {
oNode.set("role", msg.getRole().name().toLowerCase());
oNode.set("content", msg.getContent());
}
// 用户消息构建（支持多媒体）
protected void buildChatMessageNodeDo(ONode oNode, UserMessage msg) {
oNode.set("role", msg.getRole().name().toLowerCase());
if (Utils.isEmpty(msg.getMedias())) {
oNode.set("content", msg.getContent());
} else {
oNode.getOrNew("content").build(n1 -> {
if (Utils.isNotEmpty(msg.getContent())) {
n1.addNew().set("type", "text").set("text", msg.getContent());
}
// 处理图片、音频、视频等多媒体内容
for (AiMedia media : msg.getMedias()) {
if (media instanceof Image) {
n1.addNew().set("type", "image_url")
.getOrNew("image_url").set("url", media.toDataString(true));
}
// 其他媒体类型处理...
}
});
}
}
2. 工具函数标准化封装
Function Call（函数调用）是现代AI应用的重要特性，Solon-AI提供了统一的工具函数封装：
// 工具函数节点构建
protected void buildReqToolsNodeDo(ONode n, Collection<FunctionTool> tools) {
if (Utils.isEmpty(tools)) return;
n.getOrNew("tools").build(n1 -> {
for (FunctionTool func : tools) {
n1.addNew().build(n2 -> {
n2.set("type", "function");
n2.getOrNew("function").build(toolNode -> {
toolNode.set("name", func.name());
toolNode.set("description", func.description());
toolNode.set("parameters", ONode.loadStr(func.inputSchema()));
});
});
}
});
}
3. 方言适配器模式
通过方言适配器（Dialect）模式，Solon-AI实现了对不同AI服务商的兼容：
@Override
public String buildRequestJson(ChatConfig config, ChatOptions options,
List<ChatMessage> messages, boolean isStream) {
return new ONode().build(n -> {
// 模型配置
if (Utils.isNotEmpty(config.getModel())) {
n.set("model", config.getModel());
}
// 消息构建
n.getOrNew("messages").build(n1 -> {
for (ChatMessage m1 : messages) {
if (!m1.isThinking()) {
n1.add(buildChatMessageNode(m1));
}
}
});
// 流式请求标志
n.set("stream", isStream);
// 自定义选项
for (Map.Entry<String, Object> kv : options.options().entrySet()) {
n.set(kv.getKey(), ONode.loadObj(kv.getValue()));
}
// 工具函数构建
ChatMessage lastMessage = messages.get(messages.size() - 1);
buildReqToolsNode(n, config, options, lastMessage);
}).toJson();
}
实战应用示例
基础对话请求构建
// 创建聊天模型
ChatModel chatModel = ChatModel.of("https://api.example.com/v1")
.apiKey("your-api-key")
.model("gpt-4")
.build();
// 构建请求
ChatRequestDesc request = chatModel.prompt("你好，请介绍一下Solon-AI");
// 添加选项
request.options(opt -> opt
.max_tokens(1000)
.temperature(0.7f)
.top_p(0.9f));
// 执行请求
ChatResponse response = request.call();
带工具函数的复杂请求
// 定义工具函数
FunctionTool weatherTool = new FunctionToolDesc("get_weather")
.description("获取指定城市的天气信息")
.stringParamAdd("city", "城市名称")
.doHandle(args -> {
String city = (String) args.get("city");
return "{\"city\": \"" + city + "\", \"weather\": \"晴朗\", \"temp\": 25}";
});
// 构建带工具的请求
ChatRequestDesc request = chatModel.prompt("北京今天天气怎么样？")
.options(opt -> opt
.toolsAdd(weatherTool)
.tool_choice("get_weather"));
ChatResponse response = request.call();
多媒体消息请求
// 创建包含图片的用户消息
UserMessage message = ChatMessage.ofUser("请分析这张图片")
.mediaAdd(Image.ofUrl("https://example.com/image.jpg"));
ChatRequestDesc request = chatModel.prompt(message)
.options(opt -> opt
.max_tokens(500)
.temperature(0.2f));
ChatResponse response = request.call();
参数封装的优势对比
| 特性 | 原生API调用 | Solon-AI标准化封装 |
|---|---|---|
| 参数一致性 | 不同服务商参数差异大 | 统一参数接口 |
| 工具函数支持 | 需要手动构建JSON Schema | 声明式工具定义 |
| 多媒体处理 | 需要处理base64编码 | 内置多媒体支持 |
| 错误处理 | 各自为政 | 统一异常体系 |
| 扩展性 | 修改困难 | 插件化扩展 |
最佳实践建议
1. 配置管理标准化
// 使用配置类统一管理
@Configuration
public class AiConfig {
@Bean
public ChatModel chatModel(@Value("${ai.api.key}") String apiKey) {
return ChatModel.of("https://api.example.com/v1")
.apiKey(apiKey)
.model("gpt-4")
.timeout(Duration.ofSeconds(30))
.build();
}
}
2. 工具函数复用
// 创建可复用的工具库
public class WeatherTools {
@ToolMapping(description = "获取天气信息")
public static String getWeather(@Param(name = "city") String city) {
// 实现天气查询逻辑
return "{\"city\": \"" + city + "\", \"weather\": \"晴朗\"}";
}
}
// 注册工具
chatModel.options(opt -> opt.toolsAdd(new WeatherTools()));
3. 异常处理统一化
try {
ChatResponse response = request.call();
// 处理成功响应
} catch (ChatException e) {
// 统一处理AI服务异常
logger.error("AI服务调用失败: {}", e.getMessage());
throw new BusinessException("AI服务暂不可用");
}
总结
Solon-AI的请求构建机制通过标准化参数封装，为开发者提供了：
- 统一的参数接口：屏蔽不同AI服务商的参数差异
- 声明式工具定义：简化Function Call的实现复杂度
- 多媒体原生支持：内置图片、音频、视频处理能力
- 灵活的扩展机制：支持自定义方言和拦截器
- 完善的错误处理：统一的异常体系和重试机制
通过掌握Solon-AI的请求构建原理，开发者可以更高效地构建跨平台的AI应用，专注于业务逻辑而非API兼容性问题。这种标准化设计不仅提升了开发效率，也为未来的AI技术演进提供了良好的扩展基础。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
