> ## Documentation Index
> Fetch the complete documentation index at: https://java.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型集成

本指南介绍 AgentScope Java 支持的 LLM 模型及其配置方法。

## 支持的模型

| 提供商 | 类 | 流式 | 工具 | 视觉 | 推理 |
| - | - | - | - | - | - |
| DashScope | `DashScopeChatModel` | ✅ | ✅ | ✅ | ✅ |
| OpenAI | `OpenAIChatModel` | ✅ | ✅ | ✅ | ✅ |
| Anthropic | `AnthropicChatModel` | ✅ | ✅ | ✅ | ✅ |
| Gemini | `GeminiChatModel` | ✅ | ✅ | ✅ | ✅ |
| Ollama | `OllamaChatModel` | ✅ | ✅ | ✅ | ✅ |

> **注意**：
>
> * `OpenAIChatModel` 兼容 OpenAI API 规范，可用于 vLLM、DeepSeek 等提供商
> * `GeminiChatModel` 同时支持 Gemini API 和 Vertex AI

## 获取 API Key

| 提供商 | 获取地址 | 环境变量 |
| - | - | - |
| DashScope | [阿里云百炼控制台](https://bailian.console.aliyun.com/) | `DASHSCOPE_API_KEY` |
| OpenAI | [OpenAI Platform](https://platform.openai.com/api-keys) | `OPENAI_API_KEY` |
| Anthropic | [Anthropic Console](https://console.anthropic.com/settings/keys) | `ANTHROPIC_API_KEY` |
| Gemini | [Google AI Studio](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` |
| DeepSeek | [DeepSeek 开放平台](https://platform.deepseek.com/api_keys) | - |

## ModelRegistry

[`ModelRegistry`](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/model/ModelRegistry.java)（`io.agentscope.core.model.ModelRegistry`）用**字符串 id**得到 `Model` 实例，适合不想手写各厂商 `*ChatModel.builder()` 的场景。例如 Harness 场景下可使用 `HarnessAgent.builder().model(String)`；任意需要 `Model` 的地方可先调用 `ModelRegistry.resolve(...)` 再传入 `ReActAgent` 等构建器。

### API 一览

| 方法 | 说明 |
| - | - |
| `register(String name, Model model)` | 注册**具名**模型；之后对同名 id 调用 `resolve` 直接返回该实例。 |
| `registerFactory(String regex, ModelFactory factory)` | 为匹配正则的 id 注册自定义工厂；**后注册的工厂优先**于更早注册的用户工厂，且优先于内置规则。 |
| `resolve(String modelId)` | 解析并返回 `Model`；无法解析或创建失败时抛出 `IllegalArgumentException`。 |
| `canResolve(String modelId)` | 仅判断是否可解析（不创建实例）。 |
| `reset()` | 清空具名注册、用户工厂与解析缓存；内置规则保留。一般仅在测试或进程内重置时使用。 |

`ModelFactory` 为函数式接口：`Model create(String modelId)`，参数为完整模型 id 字符串。

### 内置 id 格式与环境变量

在已配置对应环境变量的前提下，可使用下列 id 形式（适用于 `resolve` 以及 `HarnessAgent.Builder.model(String)` 等）：

| id 示例 | 所需环境变量 | 说明 |
| - | - | - |
| `openai:gpt-4o-mini` | `OPENAI_API_KEY` | OpenAI 兼容 HTTP 模型 |
| `dashscope:qwen-max` | `DASHSCOPE_API_KEY` | 阿里云 DashScope / 百炼 |
| `qwen-max` 等以 `qwen-` 开头的 id | `DASHSCOPE_API_KEY` | 将整个字符串作为 DashScope 的 `modelName` |
| `anthropic:claude-sonnet-4-5-20250929` | `ANTHROPIC_API_KEY`（可选；未设置时可依赖 SDK 从环境读取） | Anthropic Claude |
| `gemini:gemini-2.5-flash` | `GEMINI_API_KEY` | Google Gemini API |
| `ollama:llama3` | `OLLAMA_BASE_URL`（可选，默认 `http://localhost:11434`） | 本地 Ollama |

同一进程内，对**相同**工厂解析 id 多次时，返回的 `Model` 实例会被缓存复用；**具名**注册不走该缓存。

### 示例：具名注册（自定义配置后复用）

需要先精细配置（温度、超时等）时，用 Builder 构建一次，再注册成名字：

```java theme={null}
import io.agentscope.core.model.GenerateOptions;
import io.agentscope.core.model.ModelRegistry;
import io.agentscope.extensions.model.openai.OpenAIChatModel;
import io.agentscope.harness.agent.HarnessAgent;

Model tuned = OpenAIChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o")
        .generateOptions(GenerateOptions.builder().temperature(0.2).build())
        .build();
ModelRegistry.register("my-gpt4o", tuned);

HarnessAgent agent = HarnessAgent.builder()
        .name("demo")
        .model("my-gpt4o")
        .workspace(workspace)
        .build();
```

### 示例：内置前缀（默认连接参数）

```java theme={null}
import io.agentscope.harness.agent.HarnessAgent;

HarnessAgent agent = HarnessAgent.builder()
        .name("demo")
        .model("dashscope:qwen-max")
        .workspace(workspace)
        .build();
```

### 示例：自定义工厂

```java theme={null}
import io.agentscope.core.model.Model;
import io.agentscope.core.model.ModelRegistry;

ModelRegistry.registerFactory(
        "my-llm:.+",
        id -> myModelFactory(id.substring("my-llm:".length())));

Model m = ModelRegistry.resolve("my-llm:prod");
```

## DashScope

阿里云 LLM 平台，提供通义千问系列模型。

```java theme={null}
DashScopeChatModel model = DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("qwen3-max")
        .build();
```

### 配置项

| 配置项 | 说明 |
| - | - |
| `apiKey` | DashScope API 密钥 |
| `modelName` | 模型名称，如 `qwen3-max`、`qwen-vl-max` |
| `baseUrl` | 自定义 API 端点（可选） |
| `stream` | 是否启用流式输出，默认 `true` |
| `enableThinking` | 启用思考模式，模型会展示推理过程 |
| `enableSearch` | 启用联网搜索，获取实时信息 |
| `endpointType` | API 端点类型（默认 `AUTO` 自动识别），可选 `TEXT`（强制文本 API）或 `MULTIMODAL`（强制多模态 API） |
| `defaultOptions` | 默认生成选项（temperature、maxTokens 等） |
| `formatter` | 消息格式化器（默认 `DashScopeChatFormatter`） |
| `nativeStructuredOutput` | 是否启用原生 `response_format` 结构化输出，默认 `false` |
| `nativeStructuredOutputWithTools` | 与工具同时使用时是否启用原生结构化输出，默认跟随 `nativeStructuredOutput` |

### 端点类型（endpointType）

DashScope 模型支持文本和多模态两种 API 端点。默认情况下，框架会根据模型名称自动识别应使用的端点类型（如 `qwen-vl-*` 以及 `qwen3.5` 系列自动使用多模态端点）。

当自动识别不准确时（例如使用自定义模型名称或兼容 API），可以手动指定端点类型：

```java theme={null}
// 强制使用多模态 API（适用于包含图片/音频等内容的场景）
DashScopeChatModel model = DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("custom-model")
        .endpointType(EndpointType.MULTIMODAL)
        .build();

// 强制使用文本 API
DashScopeChatModel model = DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("custom-model")
        .endpointType(EndpointType.TEXT)
        .build();
```

### 思考模式

```java theme={null}
DashScopeChatModel model = DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("qwen3-max")
        .enableThinking(true)
        .defaultOptions(GenerateOptions.builder()
                .thinkingBudget(5000)  // 思考 token 预算
                .build())
        .build();

OllamaChatModel model =
        OllamaChatModel.builder()
                .modelName("qwen3-max")
                .baseUrl("http://localhost:11434")
                .defaultOptions(OllamaOptions.builder()
                        .thinkOption(ThinkOption.ThinkBoolean.ENABLED)
                        .temperature(0.8)
                        .build())
                .build();
```

## OpenAI

OpenAI 模型及兼容 API。

```java theme={null}
OpenAIChatModel model = OpenAIChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o")
        .build();
```

### 兼容 API

适用于 DeepSeek、vLLM 等兼容提供商。注意需要配置对应的 Formatter 和结构化输出能力：

```java theme={null}
OpenAIChatModel model = OpenAIChatModel.builder()
        .apiKey("your-api-key")
        .modelName("deepseek-chat")
        .baseUrl("https://api.deepseek.com")
        .formatter(new DeepSeekFormatter())
        .nativeStructuredOutput(false)
        .nativeStructuredOutputWithTools(false)
        .build();
```

### 配置项

| 配置项 | 说明 |
| - | - |
| `apiKey` | API 密钥 |
| `modelName` | 模型名称，如 `gpt-4o`、`gpt-4o-mini` |
| `baseUrl` | 自定义 API 端点（可选） |
| `endpointPath` | 自定义请求路径（可选），如 `/v4/chat/completions` |
| `stream` | 是否启用流式输出，默认 `true` |
| `generateOptions` | 默认生成选项（注意：OpenAI 使用 `.generateOptions()` 而非 `.defaultOptions()`） |
| `formatter` | 消息格式化器（默认 `OpenAIChatFormatter`），兼容提供商需使用对应 Formatter（如 `DeepSeekFormatter`、`GLMFormatter`） |
| `nativeStructuredOutput` | 是否启用原生 `response_format` 结构化输出，默认 `true`。不支持的提供商（DeepSeek、vLLM 等）需设为 `false` |
| `nativeStructuredOutputWithTools` | 与工具同时使用时是否启用原生结构化输出，默认 `true`。部分提供商会优先 `response_format` 而跳过工具调用，需设为 `false` |
| `contextWindowSize` | 覆盖上下文窗口大小（可选，默认按模型名称自动推断） |
| `proxy` | 代理配置（可选），如 `ProxyConfig.http("localhost", 8080)` |

## Anthropic

Anthropic 的 Claude 系列模型。

```java theme={null}
AnthropicChatModel model = AnthropicChatModel.builder()
        .apiKey(System.getenv("ANTHROPIC_API_KEY"))
        .modelName("claude-sonnet-4-5-20250929")  // 默认值
        .build();
```

### 配置项

| 配置项 | 说明 |
| - | - |
| `apiKey` | Anthropic API 密钥 |
| `modelName` | 模型名称，默认 `claude-sonnet-4-5-20250929` |
| `baseUrl` | 自定义 API 端点（可选） |
| `stream` | 是否启用流式输出，默认 `true` |

## Gemini

Google 的 Gemini 系列模型，支持 Gemini API 和 Vertex AI。

### Gemini API

```java theme={null}
GeminiChatModel model = GeminiChatModel.builder()
        .apiKey(System.getenv("GEMINI_API_KEY"))
        .modelName("gemini-2.5-flash")  // 默认值
        .baseUrl("https://your-gateway.example")  // 可选
        .build();
```

### Vertex AI

```java theme={null}
GeminiChatModel model = GeminiChatModel.builder()
        .modelName("gemini-2.0-flash")
        .project("your-gcp-project")
        .location("us-central1")
        .vertexAI(true)
        .credentials(GoogleCredentials.getApplicationDefault())
        .build();
```

### 配置项

| 配置项 | 说明 |
| - | - |
| `apiKey` | Gemini API 密钥 |
| `baseUrl` | 自定义 Gemini API 端点（可选） |
| `modelName` | 模型名称，默认 `gemini-2.5-flash` |
| `project` | GCP 项目 ID（Vertex AI） |
| `location` | GCP 区域（Vertex AI） |
| `vertexAI` | 是否使用 Vertex AI |
| `credentials` | GCP 凭证（Vertex AI） |
| `streamEnabled` | 是否启用流式输出，默认 `true` |

如需覆盖请求端点，可使用 `baseUrl(...)`。更高级的传输层或代理配置，仍建议通过 `httpOptions(...)` 或 `clientOptions(...)` 处理。

## Ollama

自托管开源 LLM 平台，支持多种模型。

```java theme={null}
OllamaChatModel model = OllamaChatModel.builder()
        .modelName("qwen3-max")
        .baseUrl("http://localhost:11434")  // 默认值
        .build();
```

### 配置项

| 配置项 | 说明 |
| - | - |
| `modelName` | 模型名称，如 `qwen3-max`、`llama3.2`、`mistral`、`phi3` |
| `baseUrl` | Ollama 服务器端点（可选，默认 `http://localhost:11434`） |
| `defaultOptions` | 默认生成选项 |
| `formatter` | 消息格式化器（可选） |
| `httpTransport` | HTTP 传输配置（可选） |

### 高级配置

高级模型加载和生成参数：

```java theme={null}
OllamaOptions options = OllamaOptions.builder()
        .numCtx(4096)           // 上下文窗口大小
        .temperature(0.7)       // 生成随机性
        .topK(40)               // Top-K 采样
        .topP(0.9)              // 核采样
        .repeatPenalty(1.1)     // 重复惩罚
        .build();
OllamaChatModel model = OllamaChatModel.builder()
        .modelName("qwen3-max")
        .baseUrl("http://localhost:11434")
        .defaultOptions(options)  // 内部转换为 OllamaOptions
        .build();
```

### GenerateOptions 支持

Ollama 也支持 `GenerateOptions` 进行标准配置：

```java theme={null}
GenerateOptions options = GenerateOptions.builder()
        .temperature(0.7)           // 映射到 Ollama 的 temperature
        .topP(0.9)                  // 映射到 Ollama 的 top_p
        .topK(40)                   // 映射到 Ollama 的 top_k
        .maxTokens(2000)            // 映射到 Ollama 的 num_predict
        .seed(42L)                  // 映射到 Ollama 的 seed
        .frequencyPenalty(0.5)      // 映射到 Ollama 的 frequency_penalty
        .presencePenalty(0.5)       // 映射到 Ollama 的 presence_penalty
        .additionalBodyParam(OllamaOptions.ParamKey.NUM_CTX.getKey(), 4096)      // 上下文窗口大小
        .additionalBodyParam(OllamaOptions.ParamKey.NUM_GPU.getKey(), -1)        // 将所有层卸载到 GPU
        .additionalBodyParam(OllamaOptions.ParamKey.REPEAT_PENALTY.getKey(), 1.1) // 重复惩罚
        .additionalBodyParam(OllamaOptions.ParamKey.MAIN_GPU.getKey(), 0)        // 主 GPU 索引
        .additionalBodyParam(OllamaOptions.ParamKey.LOW_VRAM.getKey(), false)    // 低显存模式
        .additionalBodyParam(OllamaOptions.ParamKey.F16_KV.getKey(), true)       // 16位 KV 缓存
        .additionalBodyParam(OllamaOptions.ParamKey.NUM_THREAD.getKey(), 8)      // CPU 线程数
        .build();

OllamaChatModel model = OllamaChatModel.builder()
        .modelName("qwen3-max")
        .baseUrl("http://localhost:11434")
        .defaultOptions(OllamaOptions.fromGenerateOptions(options))  // 内部转换为 OllamaOptions
        .build();
```

### 可用参数

Ollama 支持超过 40 个参数进行精细调整：

#### 模型加载参数

* `numCtx`: 上下文窗口大小（默认：2048）
* `numBatch`: 提示处理的批处理大小（默认：512）
* `numGPU`: 卸载到 GPU 的层数（-1 表示全部）
* `lowVRAM`: 为有限 GPU 内存启用低显存模式
* `useMMap`: 使用内存映射加载模型
* `useMLock`: 锁定模型在内存中以防止交换

#### 生成参数

* `temperature`: 生成随机性（0.0-2.0）
* `topK`: Top-K 采样（标准：40）
* `topP`: 核采样（标准：0.9）
* `minP`: 最小概率阈值（默认：0.0）
* `numPredict`: 生成的最大 token 数（-1 表示无限）
* `repeatPenalty`: 重复惩罚（默认：1.1）
* `presencePenalty`: 基于 token 存在性的惩罚
* `frequencyPenalty`: 基于 token 频率的惩罚
* `seed`: 可重现结果的随机种子
* `stop`: 立即停止生成的字符串

#### 采样策略

* `mirostat`: Mirostat 采样（0=禁用，1=Mirostat v1，2=Mirostat v2）
* `mirostatTau`: Mirostat 目标熵（默认：5.0）
* `mirostatEta`: Mirostat 学习率（默认：0.1）
* `tfsZ`: 尾部自由采样（默认：1.0 禁用）
* `typicalP`: 典型概率采样（默认：1.0）

## 生成选项

通过 `GenerateOptions` 配置生成参数：

```java theme={null}
GenerateOptions options = GenerateOptions.builder()
        .temperature(0.7)           // 随机性 (0.0-2.0)
        .topP(0.9)                  // 核采样
        .topK(40)                   // Top-K 采样
        .maxTokens(2000)            // 最大输出 token 数
        .seed(42L)                  // 随机种子
        .toolChoice(new ToolChoice.Auto())  // 工具选择策略
        .build();

DashScopeChatModel model = DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("qwen3-max")
        .defaultOptions(options)
        .build();

OllamaChatModel model = OllamaChatModel.builder()
        .modelName("qwen3-max")
        .baseUrl("http://localhost:11434")
        .defaultOptions(OllamaOptions.fromGenerateOptions(options))// 内部转换为 OllamaOptions
        .build();
```

### 参数说明

| 参数 | 类型 | 说明 |
| - | - | - |
| `temperature` | Double | 控制随机性，0.0-2.0 |
| `topP` | Double | 核采样阈值，0.0-1.0 |
| `topK` | Integer | 限制候选 token 数量 |
| `maxTokens` | Integer | 最大生成 token 数 |
| `maxCompletionTokens` | Integer | 最大完成 token 数 |
| `thinkingBudget` | Integer | 思考 token 预算 |
| `reasoningEffort` | String | 推理强度（如 `low`、`medium`、`high`） |
| `frequencyPenalty` | Double | 频率惩罚，-2.0-2.0 |
| `presencePenalty` | Double | 存在惩罚，-2.0-2.0 |
| `seed` | Long | 随机种子 |
| `toolChoice` | ToolChoice | 工具选择策略 |

### 工具选择策略

```java theme={null}
new ToolChoice.Auto()              // 模型自行决定（默认）
new ToolChoice.None()              // 禁止工具调用
new ToolChoice.Required()          // 强制调用工具
new ToolChoice.Specific("tool_name")  // 强制调用指定工具
```

### 扩展参数

支持传递提供商特有的参数：

```java theme={null}
GenerateOptions options = GenerateOptions.builder()
        .additionalHeader("X-Custom-Header", "value")
        .additionalBodyParam("custom_param", "value")
        .additionalQueryParam("version", "v2")
        .build();
```

## 超时和重试

```java theme={null}
ExecutionConfig execConfig = ExecutionConfig.builder()
        .timeout(Duration.ofMinutes(2))
        .maxAttempts(3)
        .initialBackoff(Duration.ofSeconds(1))
        .maxBackoff(Duration.ofSeconds(10))
        .backoffMultiplier(2.0)
        .build();

GenerateOptions options = GenerateOptions.builder()
        .executionConfig(execConfig)
        .build();
```

## Formatter

Formatter 负责将 AgentScope 的统一消息格式转换为各 LLM 提供商的 API 格式。每个提供商有两种 Formatter：

| 提供商 | 单智能体 | 多智能体 |
| - | - | - |
| DashScope | `DashScopeChatFormatter` | `DashScopeMultiAgentFormatter` |
| OpenAI | `OpenAIChatFormatter` | `OpenAIMultiAgentFormatter` |
| Anthropic | `AnthropicChatFormatter` | `AnthropicMultiAgentFormatter` |
| Gemini | `GeminiChatFormatter` | `GeminiMultiAgentFormatter` |
| Ollama | `OllamaChatFormatter` | `OllamaMultiAgentFormatter` |

### 默认行为

不指定 Formatter 时，模型使用对应的 `ChatFormatter`，适用于单智能体场景。

### 多智能体场景

在多智能体协作（如 Pipeline、MsgHub）中，需要使用 `MultiAgentFormatter`。它会：

* 将多个智能体的消息合并为对话历史
* 使用 `<history></history>` 标签结构化历史消息
* 区分当前智能体和其他智能体的发言

```java theme={null}
// DashScope 多智能体
DashScopeChatModel model = DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("qwen3-max")
        .formatter(new DashScopeMultiAgentFormatter())
        .build();

// OpenAI 多智能体
OpenAIChatModel model = OpenAIChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o")
        .formatter(new OpenAIMultiAgentFormatter())
        .build();

// Anthropic 多智能体
AnthropicChatModel model = AnthropicChatModel.builder()
        .apiKey(System.getenv("ANTHROPIC_API_KEY"))
        .formatter(new AnthropicMultiAgentFormatter())
        .build();

// Gemini 多智能体
GeminiChatModel model = GeminiChatModel.builder()
        .apiKey(System.getenv("GEMINI_API_KEY"))
        .formatter(new GeminiMultiAgentFormatter())
        .build();

// Ollama 多智能体
OllamaChatModel model = OllamaChatModel.builder()
        .modelName("qwen3-max")
        .formatter(new OllamaMultiAgentFormatter())
        .build();
```

### 自定义历史提示

可以自定义对话历史的提示语：

```java theme={null}
String customPrompt = "# 对话记录\n以下是之前的对话内容：\n";

DashScopeChatModel model = DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("qwen3-max")
        .formatter(new DashScopeMultiAgentFormatter(customPrompt))
        .build();
```

### 何时使用 MultiAgentFormatter

| 场景 | 推荐 Formatter |
| - | - |
| 单智能体对话 | `ChatFormatter`（默认） |
| Pipeline 顺序执行 | `MultiAgentFormatter` |
| MsgHub 群聊 | `MultiAgentFormatter` |
| 多智能体辩论 | `MultiAgentFormatter` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.