展开本页目录
开始前准备什么
- JDK 21 或以上、Maven 3.9；本次环境为 JDK 25.0.2 与 Maven 3.9.14。
- 按模型目录复制支持 Chat Completions 的准确 Model ID。
- 下载完整 pom.xml 与 ChatExample.java，API Key 只放服务端环境。
- 确认框架版本
- 配置两个客户端
- 离线跑通 HTTP
- 发一次文字请求
- 核对实际费用
pom.xml、Java main 与离线 HTTP 夹具，默认只预览。
先确认 2.0 与 1.x 的接入差别
Spring AI 从 2.0.0-M5 起，OpenAI 模型底层使用官方 openai-java。本页 Maven 固定 2.0.1，传入已配置的同步和异步客户端，避免默认客户端读取其他凭据。示例不需要启动 Web 服务。
如果你的项目仍在 1.x，先查对应版本的文档和最终 URL。不要把 1.x 的 root Base URL 与 completions-path 配法直接复制到本例。
| 项目 | 本页 2.0.1 示例 | 核对方式 |
|---|---|---|
| 底层客户端 | openai-java 4.49.0 | pom.xml 固定依赖 |
| 基础地址 | https://api.apizt.com/v1 | 本地 fixture 核对最终 /v1/chat/completions |
| 框架入口 | OpenAiChatModel.builder() | 显式传两个 OpenAI 客户端 |
| Spring Boot 集成 | 2.0.x 文档支持 Boot 4.0.x / 4.1.x | 下载示例为独立 Maven main，不是完整 Boot 应用 |
- 项目
- 底层客户端
- 本页 2.0.1 示例
- openai-java 4.49.0
- 核对方式
- pom.xml 固定依赖
- 项目
- 基础地址
- 本页 2.0.1 示例
- https://api.apizt.com/v1
- 核对方式
- 本地 fixture 核对最终 /v1/chat/completions
- 项目
- 框架入口
- 本页 2.0.1 示例
- OpenAiChatModel.builder()
- 核对方式
- 显式传两个 OpenAI 客户端
- 项目
- Spring Boot 集成
- 本页 2.0.1 示例
- 2.0.x 文档支持 Boot 4.0.x / 4.1.x
- 核对方式
- 下载示例为独立 Maven main，不是完整 Boot 应用
配置客户端，模型参数从最少开始
完整文件包含 imports、客户端关闭、默认预览、离线服务器和 --run 门禁；这段只展示配置核心。首次不加 Temperature、工具、图片和流式。模型支持的 max_tokens / max_completion_tokens 要单独确认。
ChatExample.java 核心片段
var sync = OpenAIOkHttpClient.builder()
.apiKey(System.getenv("tokenba_API_KEY"))
.baseUrl("https://api.apizt.com/v1")
.maxRetries(0).timeout(Duration.ofSeconds(30)).build();
var async = OpenAIOkHttpClientAsync.builder()
.apiKey(System.getenv("tokenba_API_KEY"))
.baseUrl("https://api.apizt.com/v1")
.maxRetries(0).timeout(Duration.ofSeconds(30)).build();
var chat = OpenAiChatModel.builder()
.openAiClient(sync).openAiClientAsync(async)
.options(OpenAiChatOptions.builder()
.model(System.getenv("tokenba_MODEL"))
.temperature(null).build()).build();
var result = chat.call(new Prompt("仅回答 tokenba_OK"));
本站绘制的内容说明图：此页核心 Java 片段需要完整 imports 与依赖；首次不叠加采样、工具或流式。
下载项目后，先跑离线请求
第一条只预览；第二条启动 127.0.0.1 临时 HTTP 服务，由 Spring AI 发送一次真正的 HTTP 请求并解析固定回答。它验证依赖、序列化、路径和响应映射，不调用 apizt。第三条会调用目标型号，可能计费。
本次已核对版本、POM 和 Java 语法；Maven 依赖下载遇到连接重置，完整编译及本地 HTTP 执行尚未完成验收。下载项目后，应先在自己的环境完成编译和离线步骤，再做真实请求。
在 spring-ai 目录运行
mvn -q compile exec:java
mvn -q exec:java -Dexec.args=--offline
# 在安全环境已设置自己的 Key 与准确 Model ID 后
mvn -q exec:java -Dexec.args=--run每一层通过什么，单独记录
| 层次 | 验收内容 | 本页证据范围 |
|---|---|---|
| 构建 | 固定依赖可编译运行 | POM 与 Java 语法已检查；完整编译待验 |
| 协议 | POST /v1/chat/completions、固定回答 | fixture 已提供；本次尚未执行通过 |
| 模型 | 自己的准确 ID、权限和真实文字 | 由你的账号完成一次请求 |
| 工具 / 流式 | 工具事件回传、完整结束信号 | 需要另外测试 |
| 费用 | 本次请求的账单记录 | usage 不替代实扣 |
- 层次
- 构建
- 验收内容
- 固定依赖可编译运行
- 本页证据范围
- POM 与 Java 语法已检查；完整编译待验
- 层次
- 协议
- 验收内容
- POST /v1/chat/completions、固定回答
- 本页证据范围
- fixture 已提供；本次尚未执行通过
- 层次
- 模型
- 验收内容
- 自己的准确 ID、权限和真实文字
- 本页证据范围
- 由你的账号完成一次请求
- 层次
- 工具 / 流式
- 验收内容
- 工具事件回传、完整结束信号
- 本页证据范围
- 需要另外测试
- 层次
- 费用
- 验收内容
- 本次请求的账单记录
- 本页证据范围
- usage 不替代实扣
本站绘制的内容说明图：图明确本页尚未完成编译和端到端模型验证；不能把源码语法检查渲染成全部通过。
按报错位置修复
| 现象 | 核对 | 处理 |
|---|---|---|
| 404 / 路径重复 | 最终 URL 是否 /v1/v1/chat/completions | 按当前版本修正 Base URL |
| 401 | 客户端是否使用正确环境 Key | 检查两个客户端；不输出 Authorization |
| 400 参数不支持 | 实际发送的 temperature、token 字段 | 恢复最小参数，逐项加回 |
| 文字成功，工具失败 | 该型号是否支持 native tool calling | 保留完整工具循环再验收 |
- 现象
- 404 / 路径重复
- 核对
- 最终 URL 是否 /v1/v1/chat/completions
- 处理
- 按当前版本修正 Base URL
- 现象
- 401
- 核对
- 客户端是否使用正确环境 Key
- 处理
- 检查两个客户端；不输出 Authorization
- 现象
- 400 参数不支持
- 核对
- 实际发送的 temperature、token 字段
- 处理
- 恢复最小参数，逐项加回
- 现象
- 文字成功，工具失败
- 核对
- 该型号是否支持 native tool calling
- 处理
- 保留完整工具循环再验收
接入正式 Java 服务前
- 将 Key 留在后端密钥管理中；避免请求与响应日志泄露凭据或用户正文。
- 这个示例关闭客户端自动重试；它不具有业务防重复门禁，超时后先核对日志。
- 为真实工具增加权限、输入校验、稳定业务 ID 与持久化状态，禁止直接执行模型给出的命令。
- 升级 Spring AI、Java SDK 或模型后，复跑同一小任务并回查实际费用。
怎样确认已经完成
- pom.xml 版本与 imports 能在本地编译。
- 最终路径准确，未出现重复 /v1。
- 真实请求只发送一次，账单可对应。
- 正式功能的工具、流式与写入分别验收。
常见问题
Spring AI 的 Base URL 要不要带 /v1？
本页 2.0.1 采用官方 OpenAI Java 客户端，带 /v1。旧版本客户端与路径配置不同，应核对自己的版本和最终请求 URL。
离线显示 tokenba_OK 就代表接入成功了吗？
它只证明依赖、请求形状与响应解析。真实型号、Key 权限和计费需要在自己的账号验证。
可以直接放到已有 Spring Boot 项目吗？
先确认 Boot 与 Spring AI 版本兼容，再把客户端配置合并到自己的 Bean。下载的是独立 main 示例，没有替换你的 Web 服务结构。