企业官网建设流程全解析

LangChain4j 快速上手：在 Java 17+ 项目中 5 分钟接入 OpenAI 大模型

【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j

本文是 LangChain4j 官方入门指南（docs/docs/get-started.md）的完整实战化讲解：你将从零开始，在一个 Java 17+ 的 Maven/Gradle 项目中引入 LangChain4j 依赖，配置 OpenAI API Key，并通过几行代码构建OpenAiChatModel完成第一次与 GPT 的对话。读完本文，你将掌握 LangChain4j 的最小可运行链路，以及从低层ChatModel到高层 AI Services、再到 Quarkus/Spring Boot 集成的后续升级路径。

前置要求与环境约束

LangChain4j 对运行环境的要求非常简单，从官方文档可以提炼出两条硬性前提：

• JDK 版本：最低支持JDK 17。也就是说，任何 17 及以上的 JDK（17、21、23……）都可以直接使用。
• 一个可用的 LLM 提供商账号：LangChain4j 通过统一的 API 屏蔽各家提供商的差异，每个提供商都有独立的 Maven 依赖。本文以 OpenAI 为例。

此外，LangChain4j 的设计是模块化的：核心抽象定义在langchain4j-core，主模块langchain4j提供文档加载、聊天记忆、AI Services 等高级能力，而langchain4j-{integration}系列模块才是与各家 LLM 提供商、向量库对接的桥梁。官方文档明确指出：每个集成都有自己的 Maven 依赖，因此你可以按需引入，而不是一次性拉入整个框架。

框架用户请看这里：如果你使用的是 Quarkus、Spring Boot 或 Helidon，官方建议直接走对应的框架集成教程，而不是手动管理依赖，分别参见 Quarkus 集成指南、Spring Boot 集成指南 和 Helidon 集成指南。

第一步：引入 OpenAI 集成依赖

Maven 方式（pom.xml）

在pom.xml中加入以下依赖，即可获得与 OpenAI API 通信的全部能力：

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> <version>1.20.0</version> </dependency>

可选：引入主模块以使用 AI Services 等高层 API

langchain4j-open-ai只负责与 OpenAI 对接。如果你想使用AI Services这类高层 API（通过注解声明式地定义 LLM 服务接口，由框架自动生成实现），还需要额外添加主模块依赖：

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> <version>1.20.0</version> </dependency>

从当前仓库的 langchain4j-open-ai/pom.xml 可以看出，langchain4j-open-ai本身只依赖langchain4j-core（核心抽象）、langchain4j-http-client（HTTP 客户端抽象）等少量模块，这印证了"最小化依赖、按需组合"的设计原则。

Gradle 方式（build.gradle）

Gradle 用户对应添加：

implementation 'dev.langchain4j:langchain4j-open-ai:1.20.0' implementation 'dev.langchain4j:langchain4j:1.20.0'

第二步：用 BOM 统一管理版本（推荐）

当项目中需要引入多个 LangChain4j 模块时，手工为每个依赖维护版本号容易产生版本漂移。官方提供了Bill of Materials（BOM）机制，只需在dependencyManagement中导入一次，后续所有 LangChain4j 依赖都无需再写版本号：

<dependencyManagement> <dependencies> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-bom</artifactId> <version>1.20.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

BOM 的实现在仓库中的 langchain4j-bom/pom.xml：它通过langchain4j.stable.version与langchain4j.beta.version两个属性统一管理全部模块版本，涵盖langchain4j-core、langchain4j、langchain4j-http-client、langchain4j-open-ai等所有模块。

需要注意两点：

1. langchain4j-bom始终包含所有 LangChain4j 模块的最新版本，因此引入 BOM 相当于自动跟随主仓库的版本节奏。
2. 由于 LangChain4j 的稳定版与 beta 版并行发布，BOM 版本为1.20.0时，部分模块的实际版本仍可能是1.20.0-beta30。这些 beta 模块后续可能存在破坏性变更（breaking changes），在生产环境引入前需要关注版本说明。

第三步：尝鲜 SNAPSHOT 版本（可选）

如果你希望在功能正式发布前体验最新特性，可以使用SNAPSHOT依赖。需要在pom.xml中额外声明 Sonatype 的 SNAPSHOT 仓库：

<repositories> <repository> <name>Central Portal Snapshots</name> <id>central-portal-snapshots</id> <url>https://central.sonatype.com/repository/maven-snapshots/</url> <releases> <enabled>false</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories> <dependencies> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> <version>1.20.0-SNAPSHOT</version> </dependency> </dependencies>

SNAPSHOT 版本意味着持续集成、随时可能变化，只建议在开发环境或预发布阶段使用，不要直接用于生产。

第四步：安全地配置 API Key

官方文档给出的最佳实践是：将 API Key 存放在环境变量中，而不是硬编码在代码或提交到版本库，以降低泄露风险：

String apiKey = System.getenv("OPENAI_API_KEY");

代码运行前，需要先在操作系统层面导出该环境变量，例如：

export OPENAI_API_KEY="sk-xxxx"

这种从环境变量读取凭证的方式，在仓库的集成测试中也是标准做法。查看 OpenAiChatModelIT.java，测试类标注了@EnabledIfEnvironmentVariable(named = "OPENAI_API_KEY", matches = ".+")，即只有设置了OPENAI_API_KEY环境变量时测试才会执行，而测试内部也是通过System.getenv("OPENAI_API_KEY")读取密钥——与官方文档的推荐方式完全一致。

第五步：构建模型并完成第一次对话

创建 OpenAiChatModel 实例

使用 LangChain4j 惯用的Builder 模式构建聊天模型：

OpenAiChatModel model = OpenAiChatModel.builder() .apiKey(apiKey) .modelName("gpt-4o-mini") .build();

这里modelName("gpt-4o-mini")也可以替换为OpenAiChatModelName枚举中的常量。仓库的 OpenAiChatModelName.java 中收录了 OpenAI 主流模型及其别名，包括GPT_4_O_MINI（gpt-4o-mini）、GPT_4_O（gpt-4o）、O1、O3_MINI、O4_MINI、GPT_5_MINI等，使用枚举可以避免手写字符串拼写错误。

发起聊天

String answer = model.chat("Say 'Hello World'"); System.out.println(answer); // Hello World

OpenAiChatModel实现了langchain4j-core中定义的统一ChatModel接口（见 ChatModel.java）。因此，哪怕以后要把 OpenAI 换成其他提供商，也只需要替换模型实现类，上层代码几乎不用改动——这正是 LangChain4j "统一 API、易于切换" 的核心价值。

深入：Builder 背后还有哪些可配置项？

上面最小示例只用了apiKey和modelName两个参数，但结合 OpenAiChatModel.java 的源码，OpenAiChatModel.builder()实际暴露了非常丰富的配置入口，分为几大类：

这些配置在构造时会被合并进OpenAiChatRequestParameters，作为每次请求的默认参数下发。构建完成后调用model.chat(...)时，请求会经由统一的ChatModel接口进入doChat，最终由OpenAiClient通过 HTTP 客户端发往 OpenAI Chat Completions 端点——整条调用链在源码中清晰可见。

运行验证与常见问题

• 运行程序：确保OPENAI_API_KEY环境变量已生效，然后直接运行包含上述代码的main方法，控制台应打印Hello World。
• 看不到输出 / 401 报错：优先检查环境变量是否已正确导出（可通过echo $OPENAI_API_KEY确认），以及 API Key 是否有效。
• 想跟踪请求细节：在 Builder 中开启.logRequests(true).logResponses(true)，LangChain4j 会打印完整的 HTTP 请求与响应内容，便于快速定位问题。
• 网络受限或使用代理网关：通过.baseUrl(...)指向兼容 OpenAI 协议的端点即可，这也是仓库测试中通过OPENAI_BASE_URL环境变量覆盖地址的用法（见 OpenAiChatModelIT.java）。

接下来：从"能对话"到"构建应用"

本文完成的是 LangChain4j 的"最小可运行闭环"，它属于框架的低层抽象：直接操作ChatModel、UserMessage、AiMessage等原语，自由度高但需要自己写胶水代码。官方还提供了一条高层抽象路径：

• AI Services：用注解声明接口即可获得 LLM 能力，框架自动处理提示词、解析与工具调用，参见 AI Services 教程；
• 更多模型提供商与向量库：LangChain4j 集成了大量 LLM 提供商（OpenAI、Google Gemini、Anthropic、Ollama 本地模型等）与 Embedding/向量存储，完整清单见 语言模型集成列表 与 向量存储集成列表；
• 框架集成：企业级场景下推荐直接使用 Quarkus 集成、Spring Boot 集成 或 Helidon 集成，利用依赖注入与配置体系进一步降低开发成本。

至此，你已经具备在 Java 项目中独立接入 LangChain4j + OpenAI 的完整能力，可以在此基础上继续探索工具调用（Tools）、Agent 与 RAG 等进阶主题。

【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j