LangChain4j Chat API 入门指南前言本文基于本人在实际项目中的实践记录完整展示如何使用 LangChain4j 的 Chat API 快速接入大模型。所有代码均经过实测验证包含 Maven 依赖、Spring Boot 配置、单元测试等核心内容。一、项目环境Java 版本: JDK 17LangChain4j 1.x 最低要求Spring Boot: 3.4.5LangChain4j: 1.10.0-beta18通过 BOM 管理自动解析底层模型: 阿里云百炼通义千问兼容 OpenAI 协议二、Maven 依赖配置2.1 pom.xml?xml version1.0 encodingUTF-8?projectxmlnshttp://maven.apache.org/POM/4.0.0xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/POM4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsdmodelVersion4.0.0/modelVersionparentgroupIdcom.study.ai/groupIdartifactIdstudy-ai/artifactIdversion1.0-SNAPSHOT/version/parentartifactIdlangchain4j-01/artifactIdversion0.0.1-SNAPSHOT/versionnamelangchain4j-01/namedescriptionLangChain4j 学习入门 - 使用 OpenAI SDK/descriptiondependencies!-- LangChain4j OpenAI SDK用于调用 OpenAI API --dependencygroupIddev.langchain4j/groupIdartifactIdlangchain4j-open-ai-spring-boot-starter/artifactId/dependency!-- Spring Boot Test --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-test/artifactIdscopetest/scope/dependency/dependencies/project注意:langchain4j-open-ai-spring-boot-starter没有显式声明 version由父 POM 或 langchain4j-bom 自动管理版本。如果报错Non-resolvable import POM说明该版本未缓存到本地 Maven 仓库可尝试①检查网络连接②改用阿里云镜像③降级稳定版如 1.0.0。三、Spring Boot 应用配置3.1 application.ymllangchain4j:open-ai:chat-model:api-key:******# 【脱敏】你的阿里云 API Keymodel-name:qwen3.8-max# 选择的模型名称base-url:https://llm-k1s2eoitgcuz7t2g.cn-beijing.maas.aliyuncs.com/compatible-mode/v1# 阿里云百炼兼容接口配置说明参数含义备注api-keyAPI 认证密钥从阿里云百炼控制台获取model-name模型名称如qwen3.8-max、qwen-plus等base-url服务地址阿里云百炼采用 OpenAI 兼容协议路径为/compatible-mode/v1重要提示LangChain4j 对百炼的支持需要额外的适配层建议使用官方提供的langchain4j-bailianstarter或者确保base-url完全符合 OpenAI 协议规范。四、Spring Boot 启动类4.1 Application.javapackagecom.study.ai.langchain4j;importorg.springframework.boot.SpringApplication;importorg.springframework.boot.autoconfigure.SpringBootApplication;SpringBootApplicationpublicclassApplication{publicstaticvoidmain(String[]args){SpringApplication.run(Application.class,args);}}标准 Spring Boot 启动类无额外配置。LangChain4j 的自动配置会基于application.yml中的参数初始化ChatModelBean。五、单元测试直接调用 ChatModel5.1 ApplicationTests.javapackagecom.study.ai.langchain4j;importdev.langchain4j.model.chat.ChatModel;importorg.junit.jupiter.api.Test;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.boot.test.context.SpringBootTest;SpringBootTestclassApplicationTests{AutowiredprivateChatModelchatModel;TestvoidtestBasicChatModelResponse(){StringchattedchatModel.chat(你好你能为我做些什么);System.out.println(chatted);}}测试要点使用SpringBootTest加载完整 Spring 上下文注入已配置的ChatModelBean。调用chat()方法传入自然语言问题返回 AI 生成的回答。在 IDEA 中右键运行ApplicationTests.testBasicChatModelResponse()即可看到控制台输出。预期输出示例你好我是 Qwen3.8-Max是阿里巴巴最新推出的超大规模语言模型。我可以做很多事比如 1. **回答问题**无论是常识、专业领域还是时事热点我都能尽力解答。 2. **创作文字**写故事、写公文、写邮件、写剧本、写代码等等。 3. **表达观点**我对很多事情有自己的见解可以和你交流看法。 4. **玩游戏**你可以和我一起玩文字游戏如猜谜、成语接龙等。 5. **提供建议**如果你需要决策支持我会尽力提供帮助。 有什么问题尽管告诉我吧六、运行与调试6.1 运行测试# 方式一IDEA 右键运行# 右键 ApplicationTests → Run ApplicationTests# 方式二Maven 命令行mvn cleantest-DtestApplicationTests#testBasicChatModelResponse6.2 常见问题排查问题原因解决方案Connection refusedbase-url无法访问检查网络、API Key 是否正确Non-resolvable import POMMaven 依赖未下载成功清理~/.m2/repository下对应 jar 的.lastupdated标记后重试TimeoutException默认 60 秒超时RAG 场景需自定义timeout: PT5Mvector length mismatch集合创建未完成同步等待createCollectionAsync().join()七、下一步扩展方向基于当前最小化项目你可以继续拓展流式输出引入StreamingChatLanguageModel实现打字机效果。多轮对话使用ChatMemoryProvider维护上下文。RAG 知识库集成 Qdrant 向量数据库实现文档检索增强。工具调用定义 Function Call让 AI 自主调用订单查询等接口。Web 接口封装为 RESTful API前端实时接收流式响应。八、参考资料LangChain4j 官方文档阿里云百炼控制台学习来源JavaAI pig4cloud 中文文档感谢大佬的学习资料大家一起进步我的项目源码本文档基于实际项目实战编写所有代码均已测试通过。如有问题欢迎讨论交流