LangChain4j 接入 OpenAI 兼容接口全指南从本地 Ollama 到云端 Groq 的 ChatModel 配置实践【免费下载链接】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 官方集成文档系统讲解如何利用langchain4j-open-ai模块对接一切暴露 OpenAI 兼容 API 的服务——无论是 OrcaRouter、Tuning Engines、Groq 这类云端网关还是 Docker Model Runner、GPT4All、Ollama、LM Studio 这类本地推理工具。读完你将掌握通用三步配置法baseUrl apiKey modelName、流式响应下工具调用 ID 的accumulateToolCallId兼容开关以及 LM Studio 等 HTTP/1.1-only 服务的专项适配方案。一、核心思路OpenAI 兼容 API 的通用接入方式许多模型服务与工具都对外暴露与 OpenAI 一致的 API/v1/chat/completions风格。LangChain4j 的做法是复用OpenAiChatModel与OpenAiStreamingChatModel这两个类把请求端点替换为任意兼容服务的 Base URL从而在同一套代码框架下接入几乎所有的 LLM 后端。源码中可以看到OpenAiChatModel构建时默认使用DEFAULT_OPENAI_URL即https://api.openai.com/v1当你在 builder 中显式传入baseUrl后即覆盖默认值参见 OpenAiUtils.java 与 OpenAiChatModel.java。通用接入只需四步确定 Base URL找到目标服务的 API 端点通常以/v1结尾例如 Ollama 为http://localhost:11434/v1/OpenAI 官方为https://api.openai.com/v1。获取 API Key若服务要求鉴权则申请密钥若为本地服务且无需鉴权传入任意占位符如none即可源码中apiKey属于可选构建参数不校验格式参见 OpenAiChatModel.java。指定模型名称按服务提供方文档填写正确的模型名如gpt-3.5-turbo、deepseek-chat或本地加载的模型名该参数通常必填。配置OpenAiChatModel或OpenAiStreamingChatModel并可按需追加 temperature、timeout、日志等配置ChatModel model OpenAiChatModel.builder() .baseUrl(YOUR_API_BASE_URL) // e.g., http://localhost:8000/v1 .apiKey(YOUR_API_KEY_OR_PLACEHOLDER) // e.g., sk-yourkey 或 none .modelName(MODEL_NAME_AS_PER_PROVIDER_DOCS) // e.g., gpt-3.5-turbo 或自定义名称 // 按需追加其他配置如 temperature、timeout 等 .logRequests(true) .logResponses(true) .build();其中.logRequests(true)/.logResponses(true)用于开启请求与响应日志默认均为false参见 OpenAiChatModel.java排查联调问题时非常有用。除上述参数外OpenAiChatModelBuilder还提供了temperature、topP、stop、maxTokens、presencePenalty、frequencyPenalty、logitBias、timeout、organizationId、projectId等完整参数集参见 OpenAiChatModel.java可直接复用。二、流式响应差异accumulateToolCallId兼容开关部分 OpenAI 兼容 API 在流式streaming响应中的行为与官方实现不同尤其在工具调用tool calling场景下OpenAI 官方会把一次工具调用的 ID 拆成多个分片依次下发而 DeepSeek、Qwen 等服务的实现则是每个分片都携带完整 ID。OpenAiStreamingChatModel为此提供了accumulateToolCallId配置项true默认值跨流式分片累积工具调用 ID符合标准 OpenAI 行为。例分片 1 发送abc分片 2 发送def→ 最终 ID 为abcdef。false每个分片的 ID替换前一个适用于 DeepSeek、Qwen 等每个分片都发送完整 ID 的 API。例分片 1 发送abc分片 2 发送abc→ 最终 ID 为abc。从源码看该开关的默认值在 builder 中通过getOrDefault(builder.accumulateToolCallId, true)设定参见 OpenAiStreamingChatModel.java并在流式响应装配阶段OpenAiStreamingResponseBuilder中生效当accumulateToolCallId为true时通过idBuilder.append(...)追加拼接为false时先idBuilder.setLength(0)清空再写入当前分片从而实现替换语义参见 OpenAiStreamingResponseBuilder.java。典型配置示例以 DeepSeek 为例StreamingChatModel model OpenAiStreamingChatModel.builder() .baseUrl(https://api.deepseek.com/v1) // 或其他提供方 .apiKey(YOUR_API_KEY) .modelName(deepseek-chat) .accumulateToolCallId(false) // DeepSeek、Qwen 等需设为 false .build();注意accumulateToolCallId是OpenAiStreamingChatModel专有配置普通非流式OpenAiChatModel无此参数因为非流式响应天然携带完整 ID。三、前置条件引入langchain4j-open-ai依赖所有下述示例都基于langchain4j-open-ai模块可类比官方标准 OpenAI 示例中的ChatModel用法直接对话。请在pom.xml或 Gradle 构建文件中加入依赖Plain JavaMavendependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version1.21.0/version /dependencySpring Boot 集成dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai-spring-boot4-starter/artifactId version1.21.0/version /dependency:::notelangchain4j-open-ai-spring-boot4-starter要求Spring Boot 4若你使用Spring Boot 3请改用langchain4j-open-ai-spring-boot-starter。支持的版本组合详见 Spring Boot 集成教程。 :::以上版本号以当前仓库开发版本pom.xml 中为1.21.0-SNAPSHOT为准实际使用时请替换为你所选用的正式发布版本。四、云端 OpenAI 兼容服务接入示例以下三家为 SaaS 云端服务均需申请 API Key。4.1 OrcaRouter部署方式SaaS需 API Key简介OrcaRouter 是一个面向模型与 Agent 的 OpenAI 兼容 AI 网关与 OpenRouter 类似在单一端点后暴露跨多模型的 provider/model 命名空间同时内置自适应路由、自动故障转移、零加成推理、可观测性、护栏与 Agent 工具治理。作为 LangChain4j 的一等公民接入后可整栈使用上述能力而无需将其当作匿名自定义 Base URL 处理网关侧还能在默认拒绝default-deny策略下对每个提示/响应进行筛查、治理每个工具调用实现 AI Agent 的零信任安全且无需改动应用代码。配置方式前往 OrcaRouter 申请 API Key密钥以sk-orca-开头然后ChatModel model OpenAiChatModel.builder() .baseUrl(https://api.orcarouter.ai/v1) .apiKey(System.getenv(ORCAROUTER_API_KEY)) // 你的真实密钥如 sk-orca-... .modelName(deepseek/deepseek-v4-flash-0731) // 或 OrcaRouter 提供的其他模型 .build();可用模型名称以 OrcaRouter 的模型列表页为准。4.2 Tuning Engines部署方式SaaS需 API Key简介Tuning Engines 暴露 OpenAI 兼容端点可置于你的模型提供方之前。LangChain4j 继续承载应用与 Agent 逻辑而该端点负责集中式路由、策略控制、审计日志、追踪、审批与成本可视化。ChatModel model OpenAiChatModel.builder() .baseUrl(https://api.tuningengines.com/v1) .apiKey(System.getenv(TUNING_ENGINES_API_KEY)) .modelName(gpt-4o-mini) .build();4.3 Groq部署方式SaaS需 API Key简介Groq 以极快的 LLM 推理速度著称。前往 GroqCloud 控制台申请 API Key 后ChatModel model OpenAiChatModel.builder() .baseUrl(https://api.groq.com/openai/v1) .apiKey(System.getenv(GROQ_API_KEY)) // 或你的真实密钥 .modelName(llama3-8b-8192) // 或 Groq 提供的其他模型如 mixtral-8x7b-32768、llama3-70b-8192 .temperature(0.0) .build();可用模型名称以 Groq 官方模型列表为准。此示例展示了如何通过temperature(0.0)让输出更具确定性该参数与topP等采样参数均由 builder 直接透传至请求参见 OpenAiChatModel.java。五、本地 OpenAI 兼容服务接入示例以下四款为本地部署方案无需联网鉴权适合开发、测试或离线场景。5.1 Docker Model Runner部署方式本地简介Docker Model Runner 借助 Docker Desktop 在本地运行 LLM底层使用llama.cpp可纯 CPU 推理适用于开发、测试或离线使用支持 Mac 与 Windows。配置步骤安装 Docker Desktop在 Docker Desktop 中启用 Docker Model Runner 实验特性Settings Experimental Features Enable Docker Model Runner在该选项下方勾选 Enable host-side TCP support使用 Docker Model Runner CLI 拉取模型如docker model pull ai/qwen3。以ai/qwen3为例ChatModel model OpenAiChatModel.builder() .baseUrl(http://localhost:12434/engines/llama.cpp/v1) .modelName(ai/qwen3) .build();部分模型支持工具调用tool calling具体以 Docker 模型页面说明为准。5.2 GPT4All部署方式本地简介GPT4All 提供桌面应用可在本地运行开源 LLM并对外暴露 OpenAI 兼容 API。配置步骤下载并安装 GPT4All启动 GPT4All通过其 UI 下载所需模型如llama-3.2-1b-instruct在设置中启用 Web Server 模式Settings Application Advanced: Enable Local API Server记录 GPT4All 显示的 IP 与端口通常为http://localhost:4891/v1配置 LangChain4jChatModel model OpenAiChatModel.builder() .baseUrl(http://localhost:4891/v1) .modelName(llama-3.2-1b-instruct) // 模型名可能与 GPT4All UI 中加载的模型相关或可配置请查阅 GPT4All 文档 .build();5.3 Ollama部署方式本地简介Ollama 支持在本地运行 Llama 3、Mistral、Gemma 等开源大模型并提供 OpenAI 兼容 API 端点。需要注意LangChain4j 本身有专用的langchain4j-ollama模块参见 Ollama 集成文档本节的 OpenAI 兼容端点方式是另一种可替代方案两者可依场景选用。配置步骤安装 Ollama命令行拉取模型ollama pull model_name如ollama pull gemma3确保 Ollama 正在运行其 OpenAI 兼容 API 地址为http://localhost:11434/v1/配置 LangChain4jChatModel model OpenAiChatModel.builder() .baseUrl(http://localhost:11434/v1/) .modelName(gemma3) .build();示例参考OpenAI 兼容端点用法可直接套用通用的 OpenAI 示例若选用专用 Ollama 模块可参考langchain4j-examples仓库中的OllamaChatModelExamples。5.4 LM Studio部署方式本地简介LM Studio 提供图形化 UI用于发现、下载与运行本地 LLM并内置 OpenAI 兼容的本地服务器。配置步骤下载并安装 LM Studio通过 UISearch 标签页下载所需模型如smollm2-135m-instruct进入左侧 Developer 标签页图标形如_将服务器状态切换为 running服务器运行时右上角会显示访问地址如http://127.0.0.1:1234或通过 cURL 调用获得完整 URL关键适配LM Studio 目前不支持 HTTP/2必须强制使用 HTTP/1.1。为此需引入langchain4j-http-client-jdk依赖并将构建好的 HTTP 客户端注入模型dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-http-client-jdk/artifactId version1.21.0/version /dependencyimport java.net.http.HttpClient; import dev.langchain4j.http.client.jdk.JdkHttpClientBuilder; import dev.langchain4j.http.client.jdk.JdkHttpClient; ... HttpClient.Builder httpClientBuilder HttpClient.newBuilder() .version(HttpClient.Version.HTTP_1_1); JdkHttpClientBuilder jdkHttpClientBuilder JdkHttpClient.builder() .httpClientBuilder(httpClientBuilder); ChatModel model OpenAiChatModel.builder() .baseUrl(http://127.0.0.1:1234/v1) .modelName(smollm2-135m-instruct) .httpClientBuilder(jdkHttpClientBuilder) .build();LM Studio 示例体现了 LangChain4j HTTP 客户端的可插拔设计OpenAiChatModel的 builder 支持注入自定义HttpClientBuilder从而在不改动模型调用代码的前提下解决底层协议兼容问题。六、选型与排障速查服务部署方式Base URL是否需 API Key特殊配置OrcaRouterSaaShttps://api.orcarouter.ai/v1是sk-orca-开头无Tuning EnginesSaaShttps://api.tuningengines.com/v1是无GroqSaaShttps://api.groq.com/openai/v1是可设temperature等采样参数Docker Model Runner本地http://localhost:12434/engines/llama.cpp/v1否需启用 Host-side TCPGPT4All本地http://localhost:4891/v1否需在设置中启用 Local API ServerOllama本地http://localhost:11434/v1/否也可改用专用langchain4j-ollama模块LM Studio本地http://127.0.0.1:1234/v1否需注入 HTTP/1.1 客户端常见问题流式工具调用 ID 错乱若使用 DeepSeek、Qwen 等兼容服务且开启工具调用请将OpenAiStreamingChatModel的accumulateToolCallId设为false否则会出现 ID 被重复拼接的问题本地服务报鉴权错误本地模型一般不需要密钥apiKey传入占位符如none即可若服务端仍校验可检查是否误启用了代理或环境变量中的 OpenAI Key连接被重置 / 协议错误若目标服务不支持 HTTP/2如 LM Studio参考上文注入langchain4j-http-client-jdk并强制 HTTP/1.1模型名不识别本地服务的模型名通常等于你通过 CLI/UI 拉取或加载的模型标识云端服务则以各提供方模型列表页为准。以上所有配置与源码依据均可在此仓库内进一步验证模型实现见 OpenAiChatModel.java 与 OpenAiStreamingChatModel.java流式装配逻辑见 OpenAiStreamingResponseBuilder.javaHTTP 客户端抽象见 langchain4j-http-client 模块。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考