agentscope.model

模型模块。

class ChatModelBase

基础：object

聊天模型的基类。

__init__(model_name, stream)

初始化聊天模型基类。

Parameters:

• model_name (str) – 模型名称

• stream (bool) – 模型输出是否为流式

Return type:

无

model_name: str

模型名称

stream: bool

是否使用模型输出流式传输

abstract async __call__(*args, **kwargs)

将自己作为函数调用。

Parameters:

• 参数 (任意类型)

• kwargs (任何)

Return type:

ChatResponse | AsyncGenerator[ChatResponse, None]

class ChatResponse

基类: DictMixin

对话模型的响应。

content: Sequence[TextBlock | ToolUseBlock | ThinkingBlock]

聊天响应的内容，可包含文字区块、工具使用区块或思考区块。

id: str

唯一标识符格式化器

created_at: str

当响应被创建时

__init__(content, id=<factory>, created_at=<factory>, type=<factory>, usage=<factory>, metadata=<factory>)

Parameters:

• 内容 (序列[TextBlock | ToolUseBlock | ThinkingBlock])

• id (字符串)

• created_at (str)

• type (Literal['chat'])

• 使用情况 (ChatUsage | None)

• metadata (str | int | float | bool | None | list[JSONSerializableObject] | dict[str, JSONSerializableObject])

Return type:

无

type: Literal['chat']

响应的类型，通常为‘chat’。

usage: ChatUsage | None

聊天响应的使用信息（如果可用）。

metadata: str | int | float | bool | None | list[JSONSerializableObject] | dict[str, JSONSerializableObject]

聊天响应的元数据

class DashScopeChatModel

基类：ChatModelBase

DashScope 聊天模型类，它将生成与多模态对话 API 统一为一个方法。

__init__(model_name, api_key, stream=True, enable_thinking=None, generate_kwargs=None, base_http_api_url=None)

初始化 DashScope 聊天模型。

Parameters:

• model_name (str) – 模型名称。

• api_key (str) – 用于访问dashscope服务的API密钥。

• stream (bool) – 是否启用流式输出

• enable_thinking (bool | None, optional) – 是否启用思考功能，仅支持 Qwen3、QwQ、DeepSeek-R1。 更多详情请参见 DashScope 文档。

• generate_kwargs (dict[str, JSONSerializableObject] | None, 可选) – 用于DashScope API生成的额外关键词参数，例如 temperature, seed。

• base_http_api_url (str | None, optional) – DashScope API请求的基础URL。如果未提供，则将使用DashScope SDK的默认基础URL。

Return type:

无

async __call__(messages, tools=None, tool_choice=None, structured_model=None, **kwargs)

通过给定参数从 dashscope generation/multimodalConversation API 获取响应。

注意

我们将dashscope生成和多模态对话API统一成一个方法，因为它们支持相似的参数并共享相同的功能。

Parameters:

• messages (list[dict[str, Any]]) – 一个字典列表，其中必须包含role和content字段。

• tools (list[dict] | None, 默认 None) – 模型可以使用的工具 JSON 模式。

• tool_choice (Literal[“auto”, “none”, “any”, “required”] | str | None, default None) –

  控制模型调用哪些（如果有的话）工具。

  可以是"auto"、"none"或特定工具名称。 更多详细信息，请参考 https://help.aliyun.com/zh/model-studio/qwen-function-calling

• structured_model (Type[BaseModel] | None, 默认值 None) –

  一个Pydantic BaseModel类，用于定义模型输出的预期结构。 当提供时，模型将通过自动将BaseModel转换为工具函数并设置 tool_choice来强制使用该模式，从而强制返回符合此模式的数据。 这实现了结构化输出生成。

  注意

  当指定了structured_model时， tools和tool_choice参数都会被忽略， 模型将仅执行结构化输出生成，而不会调用任何其他工具。

• **kwargs (Any) –

  用于通义千问对话完成API的关键字参数， 例如temperature, max_tokens, top_p 等。请 查阅DashScope文档 获取更详细的参数说明。

Return type:

ChatResponse | AsyncGenerator[ChatResponse, None]

class OpenAIChatModel

基类：ChatModelBase

OpenAI 对话模型类。

__init__(model_name, api_key=None, stream=True, reasoning_effort=None, organization=None, client_args=None, generate_kwargs=None)

初始化OpenAI客户端。

Parameters:

• model_name (str, default None) – 在OpenAI API中使用的模型名称。

• api_key (str, default None) – OpenAI API 的 API 密钥。如果未指定，则会从环境变量 OPENAI_API_KEY 中读取。

• stream (bool, default True) – 是否使用流式输出。

• reasoning_effort (Literal[“low”, “medium”, “high”] | None, 可选参数) – 推理努力程度，o3、o4等模型支持。详情请参阅 OpenAI documentation 了解更多信息。

• organization (str, 默认 None) – OpenAI API的组织ID。如果未指定，将从环境变量 OPENAI_ORGANIZATION 中读取。

• client_args (dict, 默认 None) – 初始化OpenAI客户端的额外关键字参数。

• generate_kwargs (dict[str, JSONSerializableObject] | None, 可选) –

  用于OpenAI API生成的额外关键字参数，

  例如 temperature, seed。

Return type:

无

async __call__(messages, tools=None, tool_choice=None, structured_model=None, **kwargs)

通过给定参数获取OpenAI聊天完成API的响应。

Parameters:

• messages (list[dict]) – 一个字典列表，其中 role 和 content 字段是必需的，而 name 字段是可选的。

• tools (list[dict], 默认值 None) – 该模型可以使用的工具 JSON schemas。

• tool_choice (Literal["auto", "none", "any", "required"] | str | None, default None) –

  控制模型调用哪些（如果有）工具。

  可以是"auto"、"none"、"any"、"required"或特定工具名称。 更多详情请参阅 https://platform.openai.com/docs/api-reference/responses/create#responses_create-tool_choice

• structured_model (Type[BaseModel] | None, 默认 None) –

  一个定义了模型期望输出结构的Pydantic BaseModel类。当提供时，模型将通过自动将BaseModel转换为工具函数并设置tool_choice以强制其使用，来强制返回符合此模式的数据。这实现了结构化输出生成。

  注意

  当指定了structured_model时，tools和tool_choice参数都将被忽略，模型将仅执行结构化输出生成，而不调用任何其他工具。

  更多详情，请参考官方文档

• **kwargs (Any) – 适用于OpenAI聊天补全API的关键字参数， 例如temperature、max_tokens、top_p等。请 查阅OpenAI API文档以获取更多详情。

Returns:

来自OpenAI聊天补全API的回应。

Return type:

ChatResponse | 异步生成器[ChatResponse, 无]

class AnthropicChatModel

基类：ChatModelBase

Anthropic 模型包装器，用于 AgentScope。

__init__(model_name, api_key=None, max_tokens=2048, stream=True, thinking=None, client_args=None, generate_kwargs=None)

初始化Anthropic聊天模型。

Parameters:

• model_name (str) – 模型名称。

• api_key (str) – Anthropic API密钥.

• stream (bool) – 是否启用流式输出

• max_tokens (int) – 限制模型可生成的最大令牌数。

• thinking (dict | None, 默认值 None) –

  克劳德内部推理过程的配置。

  thinking示例

  {
      "type": "enabled" | "disabled",
      "budget_tokens": 1024
  }
  

• client_args （dict | None，可选）– 用于初始化Anthropic客户端的额外关键字参数。

• generate_kwargs (dict[str, JSONSerializableObject] | None, 可选) – Gemini API生成中使用的额外关键字参数， 例如 temperature, seed。

Return type:

无

async __call__(messages, tools=None, tool_choice=None, structured_model=None, **generate_kwargs)

通过所给参数从Anthropic聊天完成API获取响应。

Parameters:

• messages (list[dict]) – 一个字典列表，其中 role 和 content 字段是必需的，而 name 字段是可选的。

• tools (list[dict], default None) –

  工具JSON模式，格式如下：

  工具JSON模式示例

  [
      {
          "type": "function",
          "function": {
              "name": "xxx",
              "description": "xxx",
              "parameters": {
                  "type": "object",
                  "properties": {
                      "param1": {
                          "type": "string",
                          "description": "..."
                      },
                      # 根据需要添加更多参数
                  },
                  "required": ["param1"]
          }
      },
      # 此处可添加更多模式
  ]
  

• tool_choice (Literal["auto", "none", "any", "required"] | str | None, default None) –

  控制由模型调用哪些（如果有的话）工具。

  可选值包括"auto"、"none"、"any"、"required"，或具体的工具 名称。更多详细信息，请参阅 https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use

• structured_model (Type[BaseModel] | None, 默认值 None) –

  一个Pydantic BaseModel类，用于定义模型输出的预期结构。 当提供时，模型将通过自动将BaseModel转换为工具函数并设置 tool_choice来强制使用该模式，从而强制返回符合此模式的数据。 这实现了结构化输出生成。

  注意

  当指定了structured_model时， tools和tool_choice参数都会被忽略， 模型将仅执行结构化输出生成，而不会调用任何其他工具。

• **generate_kwargs (Any) – Anthropic聊天补全API的关键字参数， 例如 temperature, top_p等。请 参考Anthropic API文档获取更多详细信息。

Returns:

来自Anthropic聊天补全API的响应。

Return type:

ChatResponse | AsyncGenerator[ChatResponse, None]

class OllamaChatModel

基类：ChatModelBase

agentscope 中的 Ollama 聊天模型类。

__init__(model_name, stream=False, options=None, keep_alive='5m', enable_thinking=None, host=None, **kwargs)

初始化 Ollama 聊天模型。

Parameters:

• model_name (str) – 模型的名称。

• stream (bool, 默认值 True) – 是否开启流式模式。

• options (dict, 默认为 None) – 传递给Ollama API的额外参数。这些参数可以包括temperature等配置项。

• keep_alive (str, 默认值 “5m”) – 模型在内存中保持加载状态的持续时间。格式为数字后跟单位后缀（s表示秒，m表示分钟，h表示小时）。

• enable_thinking (布尔值 | 无, 默认 无) – 是否启用思考模式，仅适用于诸如 qwen3、deepseek-r1 等模型。更多详情，请参考 https://ollama.com/search?c=thinking

• host (str | None, default None) – Ollama服务器的主机地址。如果为None，则使用默认地址（通常为 http://localhost:11434）。

• **kwargs (Any) – 传递给基础聊天模型类的额外关键字参数。

Return type:

无

async __call__(messages, tools=None, tool_choice=None, structured_model=None, **kwargs)

从 Ollama 聊天补全 API 获取响应，根据给定的参数。

Parameters:

• messages (list[dict]) – 一个字典列表，其中 role 和 content 字段是必需的，而 name 字段是可选的。

• tools (list[dict], 默认值 None) – 该模型可以使用的工具 JSON schemas。

• tool_choice (Literal["auto", "none", "any", "required"] | str | None, default None) –

  控制模型调用哪些（如果有）工具。

  可以是“auto”、“none”、“any”、“required”，或者特定的工具名称。

• structured_model (Type[BaseModel] | None, default None) – 一个 Pydantic BaseModel 类，用于定义模型输出的期望结构。

• **kwargs (Any) – Ollama 聊天补全 API 的关键字参数， 例如 `think` 等。请查阅 Ollama API 文档以获取更多详情。

Returns:

来自Ollama聊天补全API的响应。

Return type:

ChatResponse | 异步生成器[ChatResponse, 无]

class GeminiChatModel

基类：ChatModelBase

agentscope 中的 Google Gemini 聊天模型类。

__init__(model_name, api_key, stream=True, thinking_config=None, client_args=None, generate_kwargs=None)

初始化 Gemini 聊天模型。

Parameters:

• model_name (str) – 要使用的Gemini模型名称，例如"gemini-2.5-flash"。

• api_key (str) – Google Gemini的API密钥。

• stream (bool, default True) – 是否使用流式输出。

• thinking_config (dict | None, 可选) –

  思维配置，支持的模型有 2.5 Pro、2.5 Flash 等。 更多详情请参阅 https://ai.google.dev/gemini-api/docs/thinking。

  thinking_config 示例

  {
      "include_thoughts": True, # 是否启用思维
      "thinking_budget": 1024   # 推理的最大令牌数
  }
  

• client_args (dict, 默认 None) – 初始化OpenAI客户端的额外关键字参数。

• generate_kwargs (dict[str, JSONSerializableObject] | None, 可选) – Gemini API 生成过程中使用的额外关键字参数， 例如 temperature, seed。

Return type:

无

async __call__(messages, tools=None, tool_choice=None, structured_model=None, **config_kwargs)

调用Gemini模型使用提供的参数。

Parameters:

• messages (list[dict[str, Any]]) – 一个字典列表，其中必须包含role和content字段。

• tools (list[dict] | None, 默认 None) – 模型可以使用的工具 JSON 模式。

• tool_choice (Literal[“auto”, “none”, “any”, “required”] | str | None, 默认 None) –

  控制模型调用哪些(如果有的话)工具。

  可以是"auto"、"none"、"any"、"required"或特定工具名称。更多详情，请参考 https://ai.google.dev/gemini-api/docs/function-calling?hl=en&example=meeting#function_calling_modes

• structured_model (Type[BaseModel] | None, 默认 None) –

  一个用于定义模型输出预期结构的 Pydantic BaseModel 类。

  注意

  当已指定 structured_model 时，tools 和 tool_choice 参数均会被忽略，模型将仅执行结构化输出生成，不调用任何其他工具。

  更多详细信息，请参考

  https://ai.google.dev/gemini-api/docs/structured-output

• **config_kwargs (Any) – Gemini 对话补全 API 的关键字参数。

Return type:

ChatResponse | AsyncGenerator[ChatResponse, None]