1. 为什么 Java 开发者需要一个统一的大模型接入层如果你正在用 Spring Boot 写业务系统突然接到需求要接大模型第一反应大概率是选哪家OpenAI、通义、DeepSeek、还是本地 Ollama每换一家SDK 换一套、鉴权换一套、参数名换一套代码里到处是if provider xxx。langchain4j 解决的正是这个问题——它把 ChatModel、EmbeddingModel、Tool、Memory 这些概念抽象成统一接口让你面向接口编程而不是面向某家厂商的 SDK 编程。但抽象层只解决了一半问题。真正落地时你仍然需要为每个模型供应商准备不同的 API Key、不同的 Base URL、不同的模型名。项目里同时接三家模型做对比测试配置文件就会变成一坨。这时候一个 OpenAI 兼容的统一通道就很有价值所有模型走同一个 endpoint、同一个 Key切换模型只改一个 model name 字符串。这篇内容面向的是已经会写 Java、想快速跑通第一个 langchain4j 应用的开发者。我会用 TaoToken 作为统一接入通道演示从 Maven 依赖、application.yml 配置、ChatModel Bean 定义到一次真实对话调用的完整链路。全程可复制跑完你就能拿到第一个AiMessage的返回文本。langchain4j 的定位不是 LangChain 的官方 Java 版它更贴合 Java 企业开发的习惯强类型、注解驱动、和 Spring Boot 集成自然。你不需要写 Python也不需要跨语言桥接一个AiService注解就能把接口变成可注入的 AI 服务。下面从最基础的依赖开始。2. TaoToken 前置准备拿到统一 Key 与 OpenAI 兼容 endpoint在写代码之前先把通道准备好。TaoToken 提供的是 OpenAI 兼容的 API 接口这意味着 langchain4j 里所有基于 OpenAI 协议的模型类都能直接指向它不需要额外的适配器。第一步是获取 API Key。访问控制台地址https://taotoken.net/console登录后在 API Keys 页面创建一个新的 Key。建议给 Key 起一个能区分用途的名字比如langchain4j-dev方便后续在多个项目间管理。创建完成后立即复制保存页面刷新后就不再完整显示。第二步是确认 Base URL。OpenAI 兼容接口的地址是https://taotoken.net/api注意这里不带任何路径后缀。langchain4j 的OpenAiChatModel会自动在这个地址后面拼接/v1/chat/completions所以你在配置里只需要填到/api这一层。如果你填成/api/v1最终请求会变成/api/v1/v1/chat/completions直接 404。第三步是选模型。在模型列表里挑一个你熟悉的比如gpt-4o-mini、claude-3-5-sonnet或者国产的deepseek-chat。记下准确的 model id后面配置里要用。不同模型的计费和能力差异较大开发阶段建议先用便宜的小模型跑通链路验证通过后再换大模型。这里有个容易踩的坑很多人以为 OpenAI 兼容就是完全一样实际上不同模型对temperature、max_tokens的取值范围要求不同。比如某些推理模型不接受temperature参数传了会报 400。langchain4j 的 builder 允许你不设置这些参数让它走默认值反而更稳。准备好这三样东西——Key、Base URL、Model ID——就可以进入代码环节了。如果你还想先确认通道是否正常可以打开模型对话页面https://taotoken.net/model-chat手动发一条消息确认能收到回复再写代码能省掉很多排查时间。3. 可复制配置Maven 依赖与 application.yml 完整片段先建一个标准的 Spring Boot 3.x 项目JDK 17 以上。langchain4j 1.x 版本对 JDK 17 支持最好JDK 8 会遇到一些模块化相关的编译问题。Maven 依赖只需要两个核心包。第一个是langchain4j-open-ai它提供了OpenAiChatModel这个类专门用于对接 OpenAI 兼容接口。第二个是langchain4j-spring-boot-starter它负责把 ChatModel 自动装配成 Bean并支持AiService注解扫描。dependencies dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version1.1.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-spring-boot-starter/artifactId version1.1.0-beta19/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies注意版本号langchain4j-open-ai用稳定版1.1.0spring-boot-starter目前还在 beta 阶段用1.1.0-beta19。两者主版本对齐避免 API 不兼容。接下来是application.yml。这里我把 Key 和 Base URL 都放在配置里实际项目建议用环境变量注入避免密钥进 Git。langchain4j: open-ai: chat-model: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} model-name: gpt-4o-mini temperature: 0.7 timeout: PT60S log-requests: true log-responses: true几个关键点说明。base-url填https://taotoken.net/api不要带/v1。api-key用${TAOTOKEN_API_KEY}从环境变量读取启动时通过export TAOTOKEN_API_KEYsk-xxx注入。log-requests和log-responses在开发阶段打开能看到实际发出的 JSON 和返回内容排查问题非常有用上线前记得关掉否则日志里会有完整的对话内容。如果你不想用 starter 的自动装配也可以手动定义 Bean。手动方式更灵活比如你想同时创建两个不同模型的 ChatModel 做对比Configuration public class ChatModelConfig { Bean public ChatModel chatModel() { return OpenAiChatModel.builder() .baseUrl(https://taotoken.net/api) .apiKey(System.getenv(TAOTOKEN_API_KEY)) .modelName(gpt-4o-mini) .temperature(0.7) .timeout(Duration.ofSeconds(60)) .logRequests(true) .logResponses(true) .build(); } }手动 Bean 和 yml 配置二选一即可同时存在会冲突。我建议开发初期用手动 Bean因为参数一目了然改起来不用查 starter 的配置前缀。4. 验证请求一次对话调用与成功结果确认配置就绪后写一个最简单的调用类来验证链路。用ApplicationRunner在启动时自动执行跑完就能在控制台看到结果。Component public class FirstChatRunner implements ApplicationRunner { Resource private ChatModel chatModel; Override public void run(ApplicationArguments args) { UserMessage userMessage UserMessage.from( 用一句话解释什么是 JVM 的类加载机制 ); ChatResponse response chatModel.chat(userMessage); AiMessage aiMessage response.aiMessage(); System.out.println(模型返回 aiMessage.text()); System.out.println(消耗 token response.tokenUsage()); } }启动项目控制台会先打印出请求日志包含完整的 JSON body你能看到model、messages、temperature这些字段。紧接着是响应日志最后是模型返回的文本。如果看到类似「JVM 的类加载机制是指将 .class 文件加载到内存并转换为运行时数据结构的过程」这样的输出说明链路完全打通。response.tokenUsage()会返回输入和输出的 token 数这个数据在成本核算时很有用。不同模型的计费单价不同但 token 统计口径基本一致。如果你想验证流式输出把chatModel.chat()换成chatModel.chat()的流式版本即可。langchain4j 提供了StreamingChatModel接口配合onNext、onComplete回调可以实现打字机效果。不过流式模式下 token 统计的时机和同步模式不同需要在onComplete里取。再进一步用AiService注解把接口变成可注入的服务这是 langchain4j 最常用的姿势AiService public interface Assistant { SystemMessage(你是一个 Java 技术专家回答简洁准确) String chat(String userMessage); }然后在 Runner 里注入Assistant直接调用assistant.chat(什么是 Spring 的 IOC)。starter 会自动为这个接口生成代理实现底层用的还是你配置的那个 ChatModel。这种方式把提示词和业务代码分离接口定义即契约非常适合团队协作。5. 本篇常见错排查401、连接失败与响应解析异常接入过程中最容易遇到三类报错我按出现频率排序。第一类是 401 Unauthorized。日志里会看到status code: 401响应体通常是{error:{message:Invalid API key}}。原因无非三种Key 没注入成功、Key 被复制时带了空格、Key 已过期或被删除。排查方法是在启动日志里确认api-key是否被正确替换如果打印出来是${TAOTOKEN_API_KEY}字面量说明环境变量没生效。用echo $TAOTOKEN_API_KEY确认一下。另外注意有些终端复制 Key 时会带上换行符建议用export TAOTOKEN_API_KEY$(cat key.txt | tr -d \n)这种方式注入。第二类是连接失败报错信息类似java.net.ConnectException或local proxy failed。如果你本地配了 HTTP 代理Java 默认会读取http.proxyHost系统属性导致请求被转发到代理然后失败。解决办法是在启动参数里加-Dhttp.proxyHost -Dhttps.proxyHost清空代理或者在代码里显式设置System.setProperty(http.proxyHost, )。还有一种情况是 Base URL 写错了比如写成了https://taotoken.net/api/v1导致路径重复。记住只填到/api。第三类是响应解析异常报错里出现reading choices或Cannot deserialize。这通常是因为返回的 JSON 结构和 langchain4j 预期的 OpenAI 格式不一致。正常情况下响应体里应该有choices数组每个元素包含message.content。如果通道返回的是错误信息但 HTTP 状态码是 200langchain4j 解析时就会找不到choices字段。打开log-responses看原始返回如果是{error:...}结构说明请求本身有问题比如 model name 写错了。模型名必须和通道支持的完全一致大小写敏感。还有一个隐蔽的坑timeout设置太短。大模型生成较长内容时响应时间可能超过 30 秒。默认超时如果不够会抛ReadTimeoutException。建议开发阶段设 60 秒生产环境根据实际模型调整。如果遇到 OAuth 相关的报错比如OAuth token exchange failed那说明你误用了需要 OAuth 鉴权的模型类。OpenAI 兼容接口用的是 Bearer Token不需要 OAuth 流程。确认你用的是OpenAiChatModel而不是AzureOpenAiChatModel或其他需要额外鉴权的类。6. 从跑通到用好统一接入后的下一步链路跑通只是起点。langchain4j 真正的价值在于它把大模型应用的常见模式都抽象好了会话记忆用ChatMemory结构化输出用AiService返回 POJO工具调用用Tool注解RAG 用EmbeddingStore加ContentRetriever。这些能力都建立在 ChatModel 之上而 ChatModel 现在指向的是统一通道意味着你换模型时上层代码一行不用改。我自己的习惯是开发阶段用便宜的小模型快速迭代提示词和业务逻辑验证通过后把model-name换成更强的模型做最终测试。因为走的是同一个 endpoint 和 Key切换成本就是改一个字符串。如果项目需要同时对比多个模型的效果可以定义多个 ChatModel Bean用Qualifier注入不同的 AiService。下一步建议你试试会话记忆。给AiService接口加上MemoryId参数配合MessageWindowChatMemory就能实现多轮对话。再往后是工具调用让模型能查数据库、调接口这才是大模型应用真正落地的地方。这些内容我会在后续文章里继续展开。如果你还没拿到 Key现在就可以去控制台创建一个把上面的配置复制进去跑一遍。遇到报错先看log-requests和log-responses的原始输出大部分问题都能从那里找到答案。 langchain4j入门：Java大模型应用开发框架的TaoToken统一接入实践
1. 为什么 Java 开发者需要一个统一的大模型接入层如果你正在用 Spring Boot 写业务系统突然接到需求要接大模型第一反应大概率是选哪家OpenAI、通义、DeepSeek、还是本地 Ollama每换一家SDK 换一套、鉴权换一套、参数名换一套代码里到处是if provider xxx。langchain4j 解决的正是这个问题——它把 ChatModel、EmbeddingModel、Tool、Memory 这些概念抽象成统一接口让你面向接口编程而不是面向某家厂商的 SDK 编程。但抽象层只解决了一半问题。真正落地时你仍然需要为每个模型供应商准备不同的 API Key、不同的 Base URL、不同的模型名。项目里同时接三家模型做对比测试配置文件就会变成一坨。这时候一个 OpenAI 兼容的统一通道就很有价值所有模型走同一个 endpoint、同一个 Key切换模型只改一个 model name 字符串。这篇内容面向的是已经会写 Java、想快速跑通第一个 langchain4j 应用的开发者。我会用 TaoToken 作为统一接入通道演示从 Maven 依赖、application.yml 配置、ChatModel Bean 定义到一次真实对话调用的完整链路。全程可复制跑完你就能拿到第一个AiMessage的返回文本。langchain4j 的定位不是 LangChain 的官方 Java 版它更贴合 Java 企业开发的习惯强类型、注解驱动、和 Spring Boot 集成自然。你不需要写 Python也不需要跨语言桥接一个AiService注解就能把接口变成可注入的 AI 服务。下面从最基础的依赖开始。2. TaoToken 前置准备拿到统一 Key 与 OpenAI 兼容 endpoint在写代码之前先把通道准备好。TaoToken 提供的是 OpenAI 兼容的 API 接口这意味着 langchain4j 里所有基于 OpenAI 协议的模型类都能直接指向它不需要额外的适配器。第一步是获取 API Key。访问控制台地址https://taotoken.net/console登录后在 API Keys 页面创建一个新的 Key。建议给 Key 起一个能区分用途的名字比如langchain4j-dev方便后续在多个项目间管理。创建完成后立即复制保存页面刷新后就不再完整显示。第二步是确认 Base URL。OpenAI 兼容接口的地址是https://taotoken.net/api注意这里不带任何路径后缀。langchain4j 的OpenAiChatModel会自动在这个地址后面拼接/v1/chat/completions所以你在配置里只需要填到/api这一层。如果你填成/api/v1最终请求会变成/api/v1/v1/chat/completions直接 404。第三步是选模型。在模型列表里挑一个你熟悉的比如gpt-4o-mini、claude-3-5-sonnet或者国产的deepseek-chat。记下准确的 model id后面配置里要用。不同模型的计费和能力差异较大开发阶段建议先用便宜的小模型跑通链路验证通过后再换大模型。这里有个容易踩的坑很多人以为 OpenAI 兼容就是完全一样实际上不同模型对temperature、max_tokens的取值范围要求不同。比如某些推理模型不接受temperature参数传了会报 400。langchain4j 的 builder 允许你不设置这些参数让它走默认值反而更稳。准备好这三样东西——Key、Base URL、Model ID——就可以进入代码环节了。如果你还想先确认通道是否正常可以打开模型对话页面https://taotoken.net/model-chat手动发一条消息确认能收到回复再写代码能省掉很多排查时间。3. 可复制配置Maven 依赖与 application.yml 完整片段先建一个标准的 Spring Boot 3.x 项目JDK 17 以上。langchain4j 1.x 版本对 JDK 17 支持最好JDK 8 会遇到一些模块化相关的编译问题。Maven 依赖只需要两个核心包。第一个是langchain4j-open-ai它提供了OpenAiChatModel这个类专门用于对接 OpenAI 兼容接口。第二个是langchain4j-spring-boot-starter它负责把 ChatModel 自动装配成 Bean并支持AiService注解扫描。dependencies dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version1.1.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-spring-boot-starter/artifactId version1.1.0-beta19/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies注意版本号langchain4j-open-ai用稳定版1.1.0spring-boot-starter目前还在 beta 阶段用1.1.0-beta19。两者主版本对齐避免 API 不兼容。接下来是application.yml。这里我把 Key 和 Base URL 都放在配置里实际项目建议用环境变量注入避免密钥进 Git。langchain4j: open-ai: chat-model: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} model-name: gpt-4o-mini temperature: 0.7 timeout: PT60S log-requests: true log-responses: true几个关键点说明。base-url填https://taotoken.net/api不要带/v1。api-key用${TAOTOKEN_API_KEY}从环境变量读取启动时通过export TAOTOKEN_API_KEYsk-xxx注入。log-requests和log-responses在开发阶段打开能看到实际发出的 JSON 和返回内容排查问题非常有用上线前记得关掉否则日志里会有完整的对话内容。如果你不想用 starter 的自动装配也可以手动定义 Bean。手动方式更灵活比如你想同时创建两个不同模型的 ChatModel 做对比Configuration public class ChatModelConfig { Bean public ChatModel chatModel() { return OpenAiChatModel.builder() .baseUrl(https://taotoken.net/api) .apiKey(System.getenv(TAOTOKEN_API_KEY)) .modelName(gpt-4o-mini) .temperature(0.7) .timeout(Duration.ofSeconds(60)) .logRequests(true) .logResponses(true) .build(); } }手动 Bean 和 yml 配置二选一即可同时存在会冲突。我建议开发初期用手动 Bean因为参数一目了然改起来不用查 starter 的配置前缀。4. 验证请求一次对话调用与成功结果确认配置就绪后写一个最简单的调用类来验证链路。用ApplicationRunner在启动时自动执行跑完就能在控制台看到结果。Component public class FirstChatRunner implements ApplicationRunner { Resource private ChatModel chatModel; Override public void run(ApplicationArguments args) { UserMessage userMessage UserMessage.from( 用一句话解释什么是 JVM 的类加载机制 ); ChatResponse response chatModel.chat(userMessage); AiMessage aiMessage response.aiMessage(); System.out.println(模型返回 aiMessage.text()); System.out.println(消耗 token response.tokenUsage()); } }启动项目控制台会先打印出请求日志包含完整的 JSON body你能看到model、messages、temperature这些字段。紧接着是响应日志最后是模型返回的文本。如果看到类似「JVM 的类加载机制是指将 .class 文件加载到内存并转换为运行时数据结构的过程」这样的输出说明链路完全打通。response.tokenUsage()会返回输入和输出的 token 数这个数据在成本核算时很有用。不同模型的计费单价不同但 token 统计口径基本一致。如果你想验证流式输出把chatModel.chat()换成chatModel.chat()的流式版本即可。langchain4j 提供了StreamingChatModel接口配合onNext、onComplete回调可以实现打字机效果。不过流式模式下 token 统计的时机和同步模式不同需要在onComplete里取。再进一步用AiService注解把接口变成可注入的服务这是 langchain4j 最常用的姿势AiService public interface Assistant { SystemMessage(你是一个 Java 技术专家回答简洁准确) String chat(String userMessage); }然后在 Runner 里注入Assistant直接调用assistant.chat(什么是 Spring 的 IOC)。starter 会自动为这个接口生成代理实现底层用的还是你配置的那个 ChatModel。这种方式把提示词和业务代码分离接口定义即契约非常适合团队协作。5. 本篇常见错排查401、连接失败与响应解析异常接入过程中最容易遇到三类报错我按出现频率排序。第一类是 401 Unauthorized。日志里会看到status code: 401响应体通常是{error:{message:Invalid API key}}。原因无非三种Key 没注入成功、Key 被复制时带了空格、Key 已过期或被删除。排查方法是在启动日志里确认api-key是否被正确替换如果打印出来是${TAOTOKEN_API_KEY}字面量说明环境变量没生效。用echo $TAOTOKEN_API_KEY确认一下。另外注意有些终端复制 Key 时会带上换行符建议用export TAOTOKEN_API_KEY$(cat key.txt | tr -d \n)这种方式注入。第二类是连接失败报错信息类似java.net.ConnectException或local proxy failed。如果你本地配了 HTTP 代理Java 默认会读取http.proxyHost系统属性导致请求被转发到代理然后失败。解决办法是在启动参数里加-Dhttp.proxyHost -Dhttps.proxyHost清空代理或者在代码里显式设置System.setProperty(http.proxyHost, )。还有一种情况是 Base URL 写错了比如写成了https://taotoken.net/api/v1导致路径重复。记住只填到/api。第三类是响应解析异常报错里出现reading choices或Cannot deserialize。这通常是因为返回的 JSON 结构和 langchain4j 预期的 OpenAI 格式不一致。正常情况下响应体里应该有choices数组每个元素包含message.content。如果通道返回的是错误信息但 HTTP 状态码是 200langchain4j 解析时就会找不到choices字段。打开log-responses看原始返回如果是{error:...}结构说明请求本身有问题比如 model name 写错了。模型名必须和通道支持的完全一致大小写敏感。还有一个隐蔽的坑timeout设置太短。大模型生成较长内容时响应时间可能超过 30 秒。默认超时如果不够会抛ReadTimeoutException。建议开发阶段设 60 秒生产环境根据实际模型调整。如果遇到 OAuth 相关的报错比如OAuth token exchange failed那说明你误用了需要 OAuth 鉴权的模型类。OpenAI 兼容接口用的是 Bearer Token不需要 OAuth 流程。确认你用的是OpenAiChatModel而不是AzureOpenAiChatModel或其他需要额外鉴权的类。6. 从跑通到用好统一接入后的下一步链路跑通只是起点。langchain4j 真正的价值在于它把大模型应用的常见模式都抽象好了会话记忆用ChatMemory结构化输出用AiService返回 POJO工具调用用Tool注解RAG 用EmbeddingStore加ContentRetriever。这些能力都建立在 ChatModel 之上而 ChatModel 现在指向的是统一通道意味着你换模型时上层代码一行不用改。我自己的习惯是开发阶段用便宜的小模型快速迭代提示词和业务逻辑验证通过后把model-name换成更强的模型做最终测试。因为走的是同一个 endpoint 和 Key切换成本就是改一个字符串。如果项目需要同时对比多个模型的效果可以定义多个 ChatModel Bean用Qualifier注入不同的 AiService。下一步建议你试试会话记忆。给AiService接口加上MemoryId参数配合MessageWindowChatMemory就能实现多轮对话。再往后是工具调用让模型能查数据库、调接口这才是大模型应用真正落地的地方。这些内容我会在后续文章里继续展开。如果你还没拿到 Key现在就可以去控制台创建一个把上面的配置复制进去跑一遍。遇到报错先看log-requests和log-responses的原始输出大部分问题都能从那里找到答案。