兼容 OpenAI 的语言模型

许多服务与工具都暴露兼容 OpenAI 的 API。将它们与 LangChain4j 配合使用的通用做法是：

确定 Base URL： 找到该服务的 API 端点。它通常以 /v1 结尾。
获取 API 密钥： 若服务需要认证，获取一个 API 密钥。若服务是本地且不要求密钥的，就把一个占位符作为 apiKey 参数。
指定模型名： 确定该服务要使用的正确模型名。这通常是必需的。

配置 OpenAiChatModel 或 OpenAiStreamingChatModel：

java

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" or "none"
        .modelName("MODEL_NAME_AS_PER_PROVIDER_DOCS") // e.g., "gpt-3.5-turbo" or custom name
        // Add other configurations like temperature, timeout, etc. as needed
        .logRequests(true)
        .logResponses(true)
        .build();

针对特定兼容 OpenAI API 的配置

一些兼容 OpenAI 的 API 在流式响应上可能有不同行为，尤其在工具调用方面。LangChain4j 提供了配置选项来处理这些差异：

`accumulateToolCallId`（用于 `OpenAiStreamingChatModel`）

控制在流式响应中如何处理工具调用 ID。默认为 true。

启用（true）：工具调用 ID 会跨流式数据块累加（标准 OpenAI 行为）
- 示例：块 1 发送 "abc"，块 2 发送 "def" → 最终 ID："abcdef"
禁用（false）：每个块的 tool call ID 会替换前一个
- 示例：块 1 发送 "abc"，块 2 发送 "abc" → 最终 ID："abc"
- 对 DeepSeek 或 Qwen 这类在每个块都发送完整工具调用 ID 的 API，请使用此项

java

StreamingChatModel model = OpenAiStreamingChatModel.builder()
        .baseUrl("https://api.deepseek.com/v1") // or other provider
        .apiKey("YOUR_API_KEY")
        .modelName("deepseek-chat")
        .accumulateToolCallId(false) // Set to false for DeepSeek, Qwen, etc.
        .build();
    ```
下面我们为流行的兼容 OpenAI API 给出具体示例，包括 OrcaRouter、Tuning Engines、Groq、Docker Model Runner、GPT4All、Ollama 与 LM Studio。

### 目录：
- [使用兼容 OpenAI 语言模型的前置条件](#使用兼容-openai-语言模型的前置条件)
- [OrcaRouter](#orcarouter)
- [Tuning Engines](#tuning-engines)
- [Groq](#groq)
- [Docker Model Runner](#docker-model-runner)
- [GPT4All](#gpt4all)
- [Ollama](#ollama)
- [LM Studio](#lm-studio)

## 使用兼容 OpenAI 语言模型的前置条件

LangChain4j 的 OpenAI 模块可与各种兼容 OpenAI 的 API 一起使用，包括本地与云端方案。对下面每个模型，我们都演示如何创建一个 `ChatModel`，你可以用它与模型对话，就像[标准 OpenAI 示例](https://github.com/langchain4j/langchain4j-examples/blob/main/open-ai-examples/src/main/java/OpenAiChatModelExamples.java)里那样。

首先，确保你的 `pom.xml` 或 Gradle 构建文件中有 OpenAI 模块：

### 纯 Java
```xml
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>1.22.0</version>
</dependency>

Spring Boot

xml

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai-spring-boot4-starter</artifactId>
    <version>1.22.0-beta32</version>
</dependency>

NOTE

该 starter 需要 Spring Boot 4。在 Spring Boot 3 上，请改用 langchain4j-open-ai-spring-boot-starter。详见 Spring Boot 集成。

OrcaRouter

部署： SaaS（需要密钥）

描述： OrcaRouter 是一个为模型与智能体同时打造的、兼容 OpenAI 的 AI 网关。与 OpenRouter 类似，它在众多模型上暴露一个 provider/model 命名空间——但它还在同一端点之后结合了自适应路由、自动故障转移、零加价推理、可观测性、护栏与工具治理。将 OrcaRouter 作为一等公民提供者接入，意味着本项目的用户可以直接使用该整套栈，而无需把 OrcaRouter 当作一个匿名的自定义 base URL。它在同一端点上以默认拒绝的方式运行网关级的零信任 AI 智能体安全——筛查每个提示词/响应并治理每个工具调用，且无需改动任何应用代码。

设置： 要使用 OrcaRouter，你需要一个来自 OrcaRouter 的 API 密钥（密钥以 sk-orca- 开头）。

配置 LangChain4j 的 OpenAiChatModel 或 OpenAiStreamingChatModel：

java

ChatModel model = OpenAiChatModel.builder()
        .baseUrl("https://api.orcarouter.ai/v1")
        .apiKey(System.getenv("ORCAROUTER_API_KEY")) // Your actual key, e.g. "sk-orca-..."
        .modelName("deepseek/deepseek-v4-flash-0731") // Or any other model offered by OrcaRouter
        .build();

你可以在 OrcaRouter 模型页找到可用的模型名。

Tuning Engines

部署： SaaS（需要密钥）

描述： Tuning Engines 暴露一个兼容 OpenAI 的端点，可以置于你的模型提供者之前。LangChain4j 保留应用与智能体逻辑，而该端点能集中管理路由、策略控制、审计日志、追踪、审批与成本可见性。

java

ChatModel model = OpenAiChatModel.builder()
        .baseUrl("https://api.tuningengines.com/v1")
        .apiKey(System.getenv("TUNING_ENGINES_API_KEY"))
        .modelName("gpt-4o-mini")
        .build();

Groq

部署： SaaS（需要密钥）

描述： Groq 为 LLM 提供极快的推理。

设置： 要使用 Groq，你需要一个来自 GroqCloud 的 API 密钥。

配置 LangChain4j 的 OpenAiChatModel 或 OpenAiStreamingChatModel：

java

ChatModel model = OpenAiChatModel.builder()
        .baseUrl("https://api.groq.com/openai/v1")
        .apiKey(System.getenv("GROQ_API_KEY")) // Or your actual key
        .modelName("llama3-8b-8192") // Or any other model offered by Groq, e.g., mixtral-8x7b-32768, llama3-70b-8192
        .temperature(0.0)
        .build();

你可以在 Groq 模型页找到可用的模型名。

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 为例（关于该模型的更多信息这里）：

java

ChatModel model = OpenAiChatModel.builder()
        .baseUrl("http://localhost:12434/engines/llama.cpp/v1")
        .modelName("ai/qwen3")
        .build();

一些模型支持工具调用，细节见 docker model 页面。

GPT4All

部署： 本地

描述： GPT4All 提供一个桌面应用，在你机器上本地运行开源 LLM。它也能暴露一个兼容 OpenAI 的 API。

设置：

从 https://gpt4all.io/ 下载并安装 GPT4All。
启动 GPT4All，通过其 UI 下载想要的模型，例如 llama-3.2-1b-instruct。
在 GPT4All 设置中启用 "Web Server" 模式（"Settings" > "Application" > 高级项下的 "Enable Local API Server"）。
记下 GPT4All 中显示的 IP 地址与端口（通常是 http://localhost:4891/v1）。
配置 LangChain4j：

java

ChatModel model = OpenAiChatModel.builder()
        .baseUrl("http://localhost:4891/v1")
        .modelName("llama-3.2-1b-instruct") // The model name might be derived from the model loaded in GPT4All UI or configurable. Check GPT4All docs.
        .build();

Ollama

尽管 LangChain4j 有一个专门的 langchain4j-ollama 模块（见 Ollama 文档），你也可以如上所示使用 OpenAI 模块连接 Ollama 的兼容 OpenAI 端点。

部署： 本地

描述： Ollama 让你在本地运行开源大语言模型，例如 Llama 3、Mistral 等。它提供一个兼容 OpenAI 的 API 端点。

设置：

从 https://ollama.ai/ 安装 Ollama。
用命令行拉取一个模型：ollama pull <model_name>（例如 ollama pull gemma3）。
确保 Ollama 正在运行。它在 http://localhost:11434/v1/ 提供一个兼容 OpenAI 的 API。
配置 LangChain4j：

java

ChatModel model = OpenAiChatModel.builder()
        .baseUrl("http://localhost:11434/v1/")
        .modelName("gemma3")
        .build();

示例：

关于兼容 OpenAI 端点的用法，请参照通用的 OpenAI 示例。
使用专门的 Ollama 模块：langchain4j-examples/.../OllamaChatModelExamples.java

LM Studio

部署： 本地

描述： LM Studio 提供一个 UI 来发现、下载并运行本地 LLM。它还有一个兼容 OpenAI 的本地服务器。

设置：

从 https://lmstudio.ai/ 下载并安装 LM Studio。
通过 LM Studio UI（Search 标签）下载你想要的模型，例如 smollm2-135m-instruct。
进入 "Developer" 标签（左侧一个形如 >_ 的图标），把服务器状态切到运行。
服务器运行时，你会在右上角看到地址（例如 http://127.0.0.1:1234）。或者，cURL 调用会给出完整 URL。
用服务器地址配置 LangChain4j：

java

ChatModel model = OpenAiChatModel.builder()
        .baseUrl("http://127.0.0.1:1234/v1")
        .modelName("smollm2-135m-instruct")
        .build();

在 1.23.0 之前的 LangChain4j 版本上，请显式配置 HTTP/1.1，参见 HTTP 版本。

语言模型

嵌入存储

决策模型

兼容 OpenAI 的语言模型

针对特定兼容 OpenAI API 的配置

`accumulateToolCallId`（用于 `OpenAiStreamingChatModel`）

Spring Boot

OrcaRouter

Tuning Engines

Groq

Docker Model Runner

GPT4All

Ollama

LM Studio

友情链接

兼容 OpenAI 的语言模型

针对特定兼容 OpenAI API 的配置

accumulateToolCallId（用于 OpenAiStreamingChatModel）

Spring Boot

OrcaRouter

Tuning Engines

Groq

Docker Model Runner

GPT4All

Ollama

LM Studio

友情链接

`accumulateToolCallId`（用于 `OpenAiStreamingChatModel`）