第5章模型集成（Model）

本章目标：掌握各种 LLM 模型的配置方法，理解生成选项和格式化器

5.1 支持的模型提供商

AgentScope-Java 支持多种主流 LLM 提供商：

提供商	模型类	流式	工具	视觉	推理	推荐场景
DashScope	`DashScopeChatModel`	✅	✅	✅	✅	国内首选
OpenAI	`OpenAIChatModel`	✅	✅	✅	-	全球通用
Anthropic	`AnthropicChatModel`	✅	✅	✅	✅	长文本
Google	`GeminiChatModel`	✅	✅	✅	✅	多模态
Ollama	`OllamaChatModel`	✅	✅	✅	✅	本地部署

5.2 DashScope（阿里云百炼）

5.2.1 基础配置

import io.agentscope.core.model.DashScopeChatModel;

// ========================================
// 【基础配置】
// ========================================
DashScopeChatModel model = DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        // API 密钥
        // - 从环境变量读取，避免硬编码
        // - 在阿里云百炼控制台获取
        
        .modelName("qwen-max")
        // 模型名称，可选值：
        // - qwen-max: 最强能力，适合复杂推理
        // - qwen-plus: 平衡性能和成本
        // - qwen-turbo: 最快速度，最低成本
        // - qwen-vl-max: 视觉理解模型
        // - qwen-audio-turbo: 音频理解模型
        
        .build();

5.2.2 高级配置

DashScopeChatModel model = DashScopeChatModel.builder()
        .apiKey(apiKey)
        .modelName("qwen-max")
        
        // ======== 流式输出 ========
        .stream(true)
        // 启用流式输出
        // - 逐 Token 返回，提升用户体验
        // - 配合 agent.stream() 使用效果最佳
        
        // ======== 思考模式 ========
        .enableThinking(true)
        // 启用思考模式
        // - 模型会返回推理过程
        // - 响应中包含 ThinkingBlock
        
        .thinkingBudget(2000)
        // 思考 Token 预算
        // - 限制推理过程的 Token 数量
        // - 仅在 enableThinking=true 时有效
        
        // ======== 联网搜索 ========
        .enableSearch(true)
        // 启用联网搜索
        // - 模型可以搜索最新信息
        // - 回答时效性问题时很有用
        
        // ======== 格式化器 ========
        .formatter(new DashScopeChatFormatter())
        // 消息格式化器
        // - 单智能体场景使用 DashScopeChatFormatter
        // - 多智能体场景使用 DashScopeMultiAgentFormatter
        
        .build();

5.2.3 可用模型列表

模型名称	能力特点	上下文长度	适用场景
`qwen-max`	最强综合能力	128K	复杂推理、代码生成
`qwen-plus`	平衡性能	128K	日常对话、内容创作
`qwen-turbo`	高速低成本	128K	简单任务、高并发
`qwen-vl-max`	视觉理解	32K	图像分析、OCR
`qwen-audio-turbo`	音频理解	-	语音转写、音频分析
`qwen3-max`	最新版本	128K	推荐使用

5.3 OpenAI 及兼容 API

5.3.1 OpenAI 原生

import io.agentscope.core.model.OpenAIChatModel;

// ========================================
// 【OpenAI 配置】
// ========================================
OpenAIChatModel model = OpenAIChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o")
        // 可选模型：
        // - gpt-4o: 最新旗舰，多模态
        // - gpt-4-turbo: 高性能
        // - gpt-3.5-turbo: 快速低成本
        
        .build();

5.3.2 OpenAI 兼容 API

许多提供商使用 OpenAI 兼容的 API 格式：

// ========================================
// 【DeepSeek】
// ========================================
OpenAIChatModel deepseekModel = OpenAIChatModel.builder()
        .apiKey(System.getenv("DEEPSEEK_API_KEY"))
        .modelName("deepseek-chat")
        .baseUrl("https://api.deepseek.com")
        .build();

// ========================================
// 【月之暗面 Moonshot】
// ========================================
OpenAIChatModel moonshotModel = OpenAIChatModel.builder()
        .apiKey(System.getenv("MOONSHOT_API_KEY"))
        .modelName("moonshot-v1-8k")
        .baseUrl("https://api.moonshot.cn/v1")
        .build();

// ========================================
// 【智谱 GLM】
// ========================================
OpenAIChatModel glmModel = OpenAIChatModel.builder()
        .apiKey(System.getenv("ZHIPU_API_KEY"))
        .modelName("glm-4")
        .baseUrl("https://open.bigmodel.cn/api/paas/v4")
        .build();

// ========================================
// 【Azure OpenAI】
// ========================================
OpenAIChatModel azureModel = OpenAIChatModel.builder()
        .apiKey(System.getenv("AZURE_OPENAI_API_KEY"))
        .modelName("gpt-4")
        .baseUrl("https://your-resource.openai.azure.com/openai/deployments/your-deployment")
        .build();

5.4 Anthropic Claude

import io.agentscope.core.model.AnthropicChatModel;

// ========================================
// 【Anthropic Claude 配置】
// ========================================
AnthropicChatModel model = AnthropicChatModel.builder()
        .apiKey(System.getenv("ANTHROPIC_API_KEY"))
        .modelName("claude-3-5-sonnet-20241022")
        // 可选模型：
        // - claude-3-5-sonnet: 最新高性能
        // - claude-3-opus: 最强能力
        // - claude-3-sonnet: 平衡
        // - claude-3-haiku: 快速
        
        .build();

5.5 Ollama 本地模型

Ollama 允许在本地运行开源模型：

import io.agentscope.core.model.OllamaChatModel;
import io.agentscope.core.model.OllamaOptions;

// ========================================
// 【Ollama 配置】
// ========================================

// 首先启动 Ollama 服务并拉取模型：
// $ ollama serve
// $ ollama pull qwen2.5:7b

OllamaChatModel model = OllamaChatModel.builder()
        .modelName("qwen2.5:7b")
        // 模型名称，需要先 pull
        // - qwen2.5:7b, qwen2.5:14b, qwen2.5:72b
        // - llama3.2, llama3.1
        // - mistral, mixtral
        
        .baseUrl("http://localhost:11434")
        // Ollama 服务地址
        // - 默认端口 11434
        
        .defaultOptions(OllamaOptions.builder()
                .numCtx(4096)        // 上下文窗口大小
                .temperature(0.7)    // 生成随机性
                .topP(0.9)           // 核采样
                .build())
        
        .build();

Ollama 常用命令：

# 启动服务
ollama serve

# 拉取模型
ollama pull qwen2.5:7b

# 查看已安装模型
ollama list

# 运行模型（命令行测试）
ollama run qwen2.5:7b

5.6 生成选项（GenerateOptions）

5.6.1 通用生成参数

import io.agentscope.core.model.GenerateOptions;
import io.agentscope.core.model.ToolChoice;

GenerateOptions options = GenerateOptions.builder()
        
        // ======== 随机性控制 ========
        
        .temperature(0.7)
        // 温度参数 (0.0 - 2.0)
        // - 0.0: 确定性输出，每次相同
        // - 0.7: 推荐值，平衡创意和一致性
        // - 1.0+: 更多创意和随机性
        
        .topP(0.9)
        // 核采样 (0.0 - 1.0)
        // - 只考虑概率累计达到 topP 的候选词
        // - 0.9: 推荐值
        
        .topK(40)
        // Top-K 采样
        // - 只考虑概率最高的 K 个候选词
        
        // ======== 输出控制 ========
        
        .maxTokens(2000)
        // 最大输出 Token 数
        // - 限制回复长度
        // - 避免过长输出消耗配额
        
        .seed(42L)
        // 随机种子
        // - 相同种子 + 相同输入 = 相同输出
        // - 用于可复现的测试
        
        .stop(List.of("END", "###"))
        // 停止序列
        // - 遇到这些字符串时停止生成
        
        // ======== 工具选择 ========
        
        .toolChoice(ToolChoice.auto())
        // 工具选择策略
        // - auto(): 模型自行决定（默认）
        // - none(): 禁止工具调用
        // - required(): 强制调用工具
        // - specific("tool_name"): 强制调用指定工具
        
        .build();

// 应用到模型
DashScopeChatModel model = DashScopeChatModel.builder()
        .apiKey(apiKey)
        .modelName("qwen-max")
        .defaultOptions(options)
        .build();

5.6.2 场景化配置建议

// ========================================
// 【代码生成】确定性、低温度
// ========================================
GenerateOptions codeOptions = GenerateOptions.builder()
        .temperature(0.2)
        .topP(0.95)
        .maxTokens(4000)
        .build();

// ========================================
// 【创意写作】高温度、更多随机性
// ========================================
GenerateOptions creativeOptions = GenerateOptions.builder()
        .temperature(1.2)
        .topP(0.95)
        .topK(50)
        .maxTokens(3000)
        .build();

// ========================================
// 【客服问答】平衡、适中温度
// ========================================
GenerateOptions qaOptions = GenerateOptions.builder()
        .temperature(0.5)
        .topP(0.9)
        .maxTokens(1000)
        .build();

// ========================================
// 【结构化输出】低温度、强制工具
// ========================================
GenerateOptions structuredOptions = GenerateOptions.builder()
        .temperature(0.1)
        .toolChoice(ToolChoice.required())
        .build();

5.7 格式化器（Formatter）

5.7.1 为什么需要格式化器

不同的 LLM API 对消息格式有不同要求。Formatter 负责将 AgentScope 的消息转换为特定 API 的格式：

┌─────────────────┐         ┌─────────────────┐
│  AgentScope Msg │ ──────► │    Formatter    │ ──────► LLM API 格式
└─────────────────┘         └─────────────────┘

5.7.2 单智能体 vs 多智能体

// ========================================
// 【单智能体场景】
// 使用标准 ChatFormatter
// ========================================
DashScopeChatModel singleAgentModel = DashScopeChatModel.builder()
        .apiKey(apiKey)
        .modelName("qwen-max")
        .formatter(new DashScopeChatFormatter())  // 默认，可省略
        .build();

// ========================================
// 【多智能体场景】
// 使用 MultiAgentFormatter
// ========================================
DashScopeChatModel multiAgentModel = DashScopeChatModel.builder()
        .apiKey(apiKey)
        .modelName("qwen-max")
        .formatter(new DashScopeMultiAgentFormatter())
        // 会将多个智能体的消息合并为结构化格式：
        // <history>
        //   <message from="Alice">...</message>
        //   <message from="Bob">...</message>
        // </history>
        .build();

重要：在 MsgHub 等多智能体场景中，必须使用 MultiAgentFormatter，否则模型无法正确区分不同智能体的消息。

5.8 超时与重试

import io.agentscope.core.ExecutionConfig;
import java.time.Duration;

// ========================================
// 【在 Agent 中配置超时和重试】
// ========================================
ReActAgent agent = ReActAgent.builder()
        .name("Assistant")
        .model(model)
        
        .modelExecutionConfig(ExecutionConfig.builder()
                .timeout(Duration.ofMinutes(2))
                // 模型调用超时
                // - 单次 API 调用的最大等待时间
                // - 超时后抛出异常或重试
                
                .maxAttempts(3)
                // 最大重试次数
                // - 网络错误、超时等情况会自动重试
                
                .retryDelay(Duration.ofSeconds(1))
                // 重试间隔
                // - 两次重试之间的等待时间
                
                .build())
        
        .toolExecutionConfig(ExecutionConfig.builder()
                .timeout(Duration.ofSeconds(30))
                .maxAttempts(2)
                .build())
        
        .build();

5.9 本章小结

本章我们学习了：

模型提供商

- DashScope：国内首选，功能完整 - OpenAI：全球通用，兼容性好 - Anthropic：长文本，推理强 - Ollama：本地部署，隐私保护

模型配置

- 基础配置：apiKey、modelName - 高级功能：流式、思考模式、联网搜索

生成选项

- 随机性控制：temperature、topP、topK - 输出控制：maxTokens、stop、seed - 工具选择：ToolChoice

格式化器

- ChatFormatter：单智能体场景 - MultiAgentFormatter：多智能体场景

超时与重试

- ExecutionConfig 配置 - 模型和工具分别配置

练习

对比模型：用同一个问题测试 qwen-max、qwen-plus、qwen-turbo，比较速度和质量
温度实验：调整 temperature 参数，观察输出变化
本地部署：使用 Ollama 运行本地模型
多模型切换：实现根据任务类型动态选择模型

下一章 → 第6章记忆系统

第5章 模型集成（Model）

第5章 模型集成（Model）

5.1 支持的模型提供商

5.2 DashScope（阿里云百炼）

5.2.1 基础配置

5.2.2 高级配置

5.2.3 可用模型列表

5.3 OpenAI 及兼容 API

5.3.1 OpenAI 原生

5.3.2 OpenAI 兼容 API

5.4 Anthropic Claude

5.5 Ollama 本地模型

5.6 生成选项（GenerateOptions）

5.6.1 通用生成参数

5.6.2 场景化配置建议

5.7 格式化器（Formatter）

5.7.1 为什么需要格式化器

5.7.2 单智能体 vs 多智能体

5.8 超时与重试

5.9 本章小结

练习

第5章模型集成（Model）

第5章模型集成（Model）