不能用RestTemplate硬调豆包API，因其无法可靠生成X-Content-Sha256和X-Signature签名头，易导致401/400错误；官方SDK内置签名、重试与流式响应解析能力，且需严格配置AK/SK、region、model三要素。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
直接用官方 volcengine-java-sdk-ark-runtime，别手写 RestTemplate 调用 —— 否则会踩签名错误、超时熔断、流式响应解析失败三大坑。
为什么不能用 RestTemplate 硬调豆包 API
豆包（火山方舟）API 要求所有请求必须带 X-Content-Sha256 和 X-Signature 签名头，且签名逻辑依赖请求体原始字节、时间戳、AK/SK 拼接与 HMAC-SHA256 计算。手写 RestTemplate 无法可靠复现该流程，常见报错包括：
401 Unauthorized: invalid signature400 Bad Request: missing required header 'X-Content-Sha256'- JSON body 被自动格式化/换行，导致签名不匹配
官方 SDK 内置了完整的签名中间件和重试策略，Spring Boot 3.x 下默认使用 HttpClient，兼容性也比手动配 OkHttp 更稳。
必须配置的三个核心参数
这三个值必须从火山方舟控制台获取，缺一不可：
立即进入“豆包AI人工智官网入口”；
立即学习“豆包AI人工智能在线问答入口”；
-
access_key_id：在「密钥管理」页生成的 AK（形如AKLTxxx），不是 API Key 字符串本身 -
secret_access_key：对应 SK（形如SKLTxxx），创建后仅显示一次，务必存进环境变量 -
model：模型 ID，例如doubao-1.5-pro-32k或doubao-1-5-vision-pro-32k-250115，注意带版本后缀
不要把 access_key_id 和控制台里那个叫 “API Key” 的字段混淆 —— 后者是旧版 Token，新 Ark 接口只认 AK/SK 对。
Spring Boot 3.x 下的正确依赖与 Bean 初始化
用 volcengine-java-sdk-ark-runtime + volc-sdk-java 组合，避免低版本 SDK 中的 io.swagger 冲突：
<dependency> <groupId>com.volcengine</groupId> <artifactId>volcengine-java-sdk-ark-runtime</artifactId> <version>1.2.0</version> </dependency> <dependency> <groupId>com.volcengine</groupId> <artifactId>volc-sdk-java</artifactId> <version>1.0.210</version> </dependency>
ArkService 必须声明为 @Bean 并注入配置，不能在方法内 new 实例 —— 否则连接池、签名器、重试策略全失效：
@Configuration
public class DoubaoConfig {
@Value("${volc.ark.access-key-id}")
private String ak;
@Value("${volc.ark.secret-access-key}")
private String sk;
@Bean
public ArkService arkService() {
return ArkService.builder()
.accessKeyId(ak)
.secretAccessKey(sk)
.region("cn-beijing") // 必须显式指定，不能省略
.build();
}
}
Region 值必须与你在控制台开通模型时选择的地域一致，比如开通页 URL 是 ark+cn-beijing，这里就填 cn-beijing，填错会返回 403 Forbidden: region not authorized。
调用时最容易漏掉的两个细节
即使签名和配置都对，ChatCompletionRequest 构造不对也会静默失败或返回空响应：
- 必须显式设置
.stream(false)（默认是true），否则返回的是ServerSentEvent流，Spring Web 默认不处理，会卡住或抛IOException -
messages列表至少含一条USER角色消息，不能只传system；若需系统提示，应拆成两条：system+user
一个最小可用示例：
public String ask(String question) {
List<ChatMessage> messages = Arrays.asList(
ChatMessage.builder().role(ChatMessageRole.SYSTEM).content("请用中文简洁回答").build(),
ChatMessage.builder().role(ChatMessageRole.USER).content(question).build()
);
ChatCompletionRequest req = ChatCompletionRequest.builder()
.model("doubao-1.5-pro-32k")
.messages(messages)
.stream(false) // 关键！
.build();
ChatCompletionResponse resp = arkService.chatCompletion(req);
return resp.getChoices().get(0).getMessage().getContent();
}
真正上线前，记得检查 application.yml 里是否禁用了 spring.main.allow-circular-references=true —— 官方 SDK 的某些内部 Bean 依赖链在 Spring Boot 3.2+ 默认会触发循环引用报错，这个开关现在是刚需，不是可选项。
