跳至主要內容

请求响应参数

BladeX大约 7 分钟modelparameters

大模型请求响应参数详解

参数规范

BladeX AI大模型模块采用统一的请求响应参数规范，兼容主流大模型API标准，同时提供扩展机制支持模型特有参数。本文档详细说明了所有支持的参数及其使用方法。

一、请求参数详解

1.1 BladeChatRequest 核心参数

完整参数列表

BladeChatRequest提供了丰富的参数配置选项，支持模型选择、对话管理、生成控制等多种功能。

BladeChatRequest request = BladeChatRequest.builder()
    .model("gpt-3.5-turbo")                    // 模型名称
    .messages(messageList)                     // 消息列表
    .conversationId(123456L)                   // 会话ID
    .temperature(0.7)                          // 温度参数
    .topP(0.9)                                // 核采样参数
    .maxTokens(2000)                          // 最大生成token数
    .stream(false)                            // 是否流式响应
    .stop(Arrays.asList("\\n", "END"))        // 停止标记
    .frequencyPenalty(0.0)                    // 频率惩罚
    .presencePenalty(0.0)                     // 重复惩罚
    .functions(functionList)                   // 工具函数定义
    .functionCall("auto")                      // 工具函数调用模式
    .user("user123")                          // 用户标识
    .ip("192.168.1.100")                      // 用户IP
    .chatClient(clientConfig)                  // 客户端配置
    .extraParams(customParams)                 // 扩展参数
    .build();

1.2 核心参数说明

参数名称类型必填默认值说明
modelString✅-模型名称，如gpt-3.5-turbo
messagesList<ChatMessage>✅-对话消息列表
conversationIdLong❌null会话ID，用于多轮对话
temperatureDouble❌0.7温度参数，控制随机性(0-2)
topPDouble❌1.0核采样参数，控制多样性(0-1)
maxTokensInteger❌2000最大生成token数
streamBoolean❌false是否启用流式响应

1.3 高级参数配置

高级参数

高级参数配置包括停止标记、惩罚参数和用户标识等，用于精细化控制模型行为。

// 停止标记配置
.stop(Arrays.asList("\\n", "END", "STOP"))

// 惩罚参数配置
.frequencyPenalty(0.5)    // 频率惩罚，减少重复内容
.presencePenalty(0.3)     // 存在惩罚，鼓励新话题

// 用户标识配置
.user("user_12345")       // 用户唯一标识
.ip("192.168.1.100")      // 用户IP地址

1.4 消息格式规范

ChatMessage 结构

ChatMessage定义了对话消息的标准格式，支持不同角色的消息类型和可选的扩展字段。

ChatMessage message = ChatMessage.builder()
    .role("user")                    // 角色：user/assistant/system
    .content("你好，请介绍一下自己")    // 消息内容
    .name("张三")                    // 发送者名称（可选）
    .functionCall(functionCall)      // 函数调用信息（可选）
    .build();

角色类型说明：

  • system：系统提示词，设定AI行为
  • user：用户消息
  • assistant：AI助手回复
  • function：函数调用结果（部分模型支持）

1.5 工具函数配置

Function Calling

工具函数配置支持Function Calling功能，允许模型调用外部函数来获取信息或执行操作。

// 函数定义
Map<String, Object> function = Map.of(
    "name", "get_weather",
    "description", "获取指定城市的天气信息",
    "parameters", Map.of(
        "type", "object",
        "properties", Map.of(
            "city", Map.of(
                "type", "string",
                "description", "城市名称"
            )
        ),
        "required", Arrays.asList("city")
    )
);

// 请求配置
.functions(Arrays.asList(function))
.functionCall("auto")  // auto/none/{"name": "function_name"}

1.6 扩展参数机制

模型特有参数

扩展参数机制允许传递模型特有的参数，支持不同模型提供商的个性化配置。

// 通过extraParams传递模型特有参数
Map<String, Object> extraParams = new HashMap<>();
extraParams.put("repetition_penalty", 1.1);    // 重复惩罚（部分模型）
extraParams.put("do_sample", true);            // 采样开关（部分模型）
extraParams.put("num_beams", 4);               // 束搜索（部分模型）

.extraParams(extraParams)

二、响应参数详解

2.1 BladeChatResponse 结构

完整响应结构

BladeChatResponse提供了标准化的响应格式，包含响应元数据、生成内容和使用统计等信息。

BladeChatResponse response = BladeChatResponse.builder()
    .id("chatcmpl-123456")                     // 响应唯一ID
    .object("chat.completion")                 // 对象类型
    .created(1677652288)                       // 创建时间戳
    .model("gpt-3.5-turbo")                   // 使用的模型
    .choices(choiceList)                       // 响应选择列表
    .usage(usage)                             // Token使用统计
    .result(result)                           // 完成状态
    .build();

2.2 响应字段说明

字段名称类型说明
idString响应的唯一标识符
objectString对象类型，通常为"chat.completion"
createdIntegerUnix时间戳，响应创建时间
modelString实际使用的模型名称
choicesList<ChatChoice>生成的回复选择列表
usageChatUsageToken使用统计信息
resultChatResult生成完成状态

2.3 ChatChoice 详解

选择项结构

ChatChoice包含了模型生成的具体内容，支持同步和流式两种响应模式。

ChatChoice choice = ChatChoice.builder()
    .index(0)                                  // 选择项索引
    .message(message)                          // 完整消息（同步模式）
    .delta(delta)                             // 增量消息（流式模式）
    .finishReason("stop")                     // 结束原因
    .build();

结束原因说明：

  • stop：正常结束
  • length：达到最大长度限制
  • function_call：需要调用函数
  • content_filter：内容被过滤

2.4 Token使用统计

ChatUsage 结构

ChatUsage提供了详细的Token使用统计信息，用于成本计算和使用量监控。

ChatUsage usage = ChatUsage.builder()
    .promptTokens(50)                         // 输入token数
    .completionTokens(100)                    // 输出token数
    .totalTokens(150)                         // 总token数
    .build();

Token计费说明：

  • promptTokens：用户输入和系统提示消耗的token
  • completionTokens：AI生成内容消耗的token
  • totalTokens：总消耗token数，用于计费

2.5 流式响应差异

流式vs同步

同步响应：

  • message字段包含完整回复
  • finishReason表示最终结束状态
  • usage包含完整token统计

流式响应：

  • delta字段包含增量内容
  • 最后一个chunk的finishReason不为null
  • usage仅在最后一个chunk中提供

三、参数验证规则

3.1 必填参数验证

验证规则

系统对必填参数进行严格验证，确保请求的完整性和有效性。

// 必填参数检查
if (StringUtil.isBlank(request.getModel())) {
    throw LlmException.invalidParam("模型名称不能为空");
}
if (CollectionUtil.isEmpty(request.getMessages())) {
    throw LlmException.invalidParam("消息列表不能为空");
}

3.2 参数范围验证

数值范围限制

数值参数需要在指定范围内，超出范围将抛出参数验证异常。

// 温度参数验证
if (temperature != null && (temperature < 0 || temperature > 2)) {
    throw LlmException.invalidParam("temperature参数范围为0-2");
}

// topP参数验证
if (topP != null && (topP < 0 || topP > 1)) {
    throw LlmException.invalidParam("topP参数范围为0-1");
}

// maxTokens参数验证
if (maxTokens != null && maxTokens <= 0) {
    throw LlmException.invalidParam("maxTokens必须大于0");
}

3.3 消息格式验证

消息验证

消息格式验证确保消息角色和内容的有效性，防止无效请求。

// 消息角色验证
Set<String> validRoles = Set.of("system", "user", "assistant", "function");
if (!validRoles.contains(message.getRole())) {
    throw LlmException.invalidParam("无效的消息角色: " + message.getRole());
}

// 消息内容验证
if (StringUtil.isBlank(message.getContent()) && message.getFunctionCall() == null) {
    throw LlmException.invalidParam("消息内容不能为空");
}

四、模型特有参数

4.1 OpenAI 特有参数

OpenAI 扩展参数

OpenAI模型支持的特有参数，包括惩罚参数、词汇偏置、随机种子等高级配置。

// OpenAI特有参数
Map<String, Object> openaiParams = Map.of(
    "frequency_penalty", 0.5,      // 频率惩罚
    "presence_penalty", 0.3,       // 存在惩罚
    "logit_bias", logitBias,       // 词汇偏置
    "n", 1,                        // 生成选择数量
    "seed", 12345                  // 随机种子
);

4.2 Anthropic 特有参数

Claude 扩展参数

Anthropic Claude模型的特有参数配置，包括系统提示、元数据和停止序列。

// Anthropic特有参数
Map<String, Object> anthropicParams = Map.of(
    "system", "你是一个有用的AI助手",  // 系统提示
    "metadata", metadata,             // 元数据
    "stop_sequences", stopList        // 停止序列
);

4.3 DeepSeek 特有参数

DeepSeek 扩展参数

DeepSeek模型支持的特有参数，包括重复惩罚、采样控制和束搜索配置。

// DeepSeek特有参数
Map<String, Object> deepseekParams = Map.of(
    "repetition_penalty", 1.1,     // 重复惩罚
    "do_sample", true,             // 启用采样
    "num_beams", 1                 // 束搜索数量
);

五、错误处理

5.1 参数错误响应

错误格式

参数错误时返回标准化的错误响应格式，包含错误类型、代码和详细信息。

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "temperature参数范围为0-2",
    "param": "temperature"
  }
}

5.2 常见错误类型

错误类型错误代码说明
参数错误invalid_parameter参数值不在有效范围内
缺失参数missing_parameter必填参数未提供
模型不存在model_not_found指定的模型不存在
配额超限quota_exceeded超出使用配额限制
内容过滤content_filtered内容被安全过滤器拦截

六、最佳实践

6.1 参数优化建议

优化建议

性能优化：

  • 合理设置maxTokens，避免不必要的长回复
  • 流式调用适用于需要实时反馈的场景
  • 使用conversationId维护多轮对话上下文

质量优化：

  • temperature设为0.7-0.9获得平衡的创造性
  • 使用stop参数控制回复格式
  • 通过system消息设定AI行为规范

6.2 安全注意事项

安全建议

  • 验证用户输入，防止注入攻击
  • 设置合理的maxTokens限制，控制成本
  • 记录user和ip信息，便于审计
  • 敏感场景下禁用functions功能

通过合理配置请求参数和正确解析响应参数，可以充分发挥BladeX AI大模型模块的强大能力，为应用提供高质量的AI对话服务。

上次编辑于:
贡献者: smallchill