类class agentscope.model

ChatModelBase

class ChatModelBase

源码Source agentscope/model/_base.py:37–751

ChatModelBase 是所有聊天模型的抽象基类，统一流式与非流式调用、token 计数、重试和结构化输出。上层代码只依赖这个基类即可切换供应商。位于 agentscope.model 包。核心成员包括 list_models、count_tokens、generate_structured_output。

The base class for chat models. Declared in agentscope.model.

核心精讲Deep dive

ChatModelBase：模型抽象ChatModelBase: the model abstraction

ChatModelBase 是所有聊天模型的抽象基类，统一流式与非流式调用、token 计数、重试和结构化输出。上层代码只依赖这个基类即可切换供应商。

ChatModelBase is the abstraction shared by all chat models. It unifies streaming and non-streaming calls, token counting, retries and structured output so upper layers can switch providers without code changes.

子类实现供应商协议；对上层只暴露 __call__ 这一入口。Subclasses implement the provider protocol; callers only use __call__.
stream=True 时返回异步生成器，stream=False 时返回完整的 ChatResponse。With stream=True it returns an async generator; with stream=False it returns a complete ChatResponse.
max_retries、retry_delay 与 context_size 由基类统一管理。max_retries, retry_delay and context_size are managed by the base class.

面向基类编程Program against the base type

import asyncio
import os

from agentscope.credential import OpenAICredential
from agentscope.message import UserMsg
from agentscope.model import ChatModelBase, OpenAIChatModel


async def main() -> None:
    model: ChatModelBase = OpenAIChatModel(
        credential=OpenAICredential(api_key=os.environ["OPENAI_API_KEY"]),
        model="gpt-4.1-mini",
        stream=False,
    )
    response = await model([UserMsg("user", "Hello")])
    print(response.content)


asyncio.run(main())

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`Parameters`	类class	参数，与模型服务通信并返回生成或向量化结果。 Each subclass should implement this inner class to define its parameters.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(credential:` `CredentialBase, model: str, parameters: BaseModel, stream: bool = True, max_retries: int = 3,…`	初始化模型的凭据、名称、采样参数与重试策略。 Initialize the chat model base.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`credential`	CredentialBase	凭证字段。	—
`model`	str	模型字段。	—
`stream`	bool	流字段。	—
`max_retries`	int	最大重试字段。	—
`retry_delay`	float	重试延迟字段。	—
`context_size`	int	上下文大小字段。	—

方法摘要Method Summary

方法Method	说明Description
`def list_models(custom_yaml_dir: str \| None = None) -> list[ModelCard]`	列出当前凭据可用的模型卡片。 List candidate models of the API.
`async def __call__(messages: list[Msg], tools: list[dict] \| None = None, tool_choice: ToolChoice \| None = None, **kwarg…`async	调用模型并返回完整响应或流式响应生成器。 Call the model with retry logic.
`async def count_tokens(messages: list[Msg], tools: list[dict] \| None) -> int`async	估算消息与工具模式占用的 token 数。 A quick and unified method to estimate the token count of the model input by dividing the total input size in bytes by 4.
`async def generate_structured_output(messages: list[Msg], structured_model: Type[BaseModel] \| dict, **kwargs: Any) -> S…`async	按 Pydantic 模型或 JSON 模式生成结构化结果。 Generate structured output, trying fallback strategies in order.

构造器详情Constructor Detail

ChatModelBase

def __init__(credential: CredentialBase, model: str, parameters: BaseModel, stream: bool = True, max_retries: int = 3, retry_delay: float = 1.0, context_size: int = 32768) -> None

初始化 ChatModelBase 实例。

Initialize the chat model base.

参数Parameters

名称Name	类型Type	说明Description
`credential`	CredentialBase	API 凭证。The API credential.
`model`	str	模型名称。The model name.
`parameters`	BaseModel	模型参数。The model parameters.
`stream`默认default `True`	bool	判断是否到启用流式输出用于大模型。Whether to enable streaming output for the LLM.
`max_retries`默认default `3`	int	最大重试次数（类型 `int`）。The maximum number of retries for API calls. Only exceptions listed in `_get_retryable_exceptions()` count against this budget; other exceptions are raised immediately.
`retry_delay`默认default `1.0`	float	重试延迟（类型 `float`）。Seconds to sleep between retry attempts.
`context_size`默认default `32768`	int	上下文大小（类型 `int`）。The model context size used for context compression.

源码Source agentscope/model/_base.py:62–98

属性详情Attribute Detail

credential

CredentialBase

凭证字段。声明为 CredentialBase。

The credential field.

源码Source agentscope/model/_base.py:44

model

str

模型字段。声明为 str。

The model field.

源码Source agentscope/model/_base.py:47

stream

bool

流字段。声明为 bool。

The stream field.

源码Source agentscope/model/_base.py:50

max_retries

int

最大重试字段。声明为 int。

The max retries field.

源码Source agentscope/model/_base.py:53

retry_delay

float

重试延迟字段。声明为 float。

The retry delay field.

源码Source agentscope/model/_base.py:56

context_size

int

上下文大小字段。声明为 int。

The context size field.

源码Source agentscope/model/_base.py:59

方法详情Method Detail

list_models

def list_models(custom_yaml_dir: str | None = None) -> list[ModelCard]

列出模型。

List candidate models of the API.

参数Parameters

名称Name	类型Type	说明Description
`custom_yaml_dir`默认default `None`	str \| None	自定义 YAML 目录。The custom YAML directory.

返回Returns list[ModelCard]

返回ModelCard列表。`list[ModelCard]`:

源码Source agentscope/model/_base.py:135–182

call

async def __call__(messages: list[Msg], tools: list[dict] | None = None, tool_choice: ToolChoice | None = None, **kwargs: Any) -> ChatResponse | AsyncGenerator[ChatResponse, None]

async

以可调用对象方式执行。

Attempts to call the model up to max_retries + 1 times.

参数Parameters

名称Name	类型Type	说明Description
`messages`	list[Msg]	消息到发送到模型。The messages to send to the model.
`tools`默认default `None`	list[dict] \| None	工具可用到模型。The tools available to the model.
`tool_choice`默认default `None`	ToolChoice \| None	工具选项模式或函数名称。The tool choice mode or function name.
`kwargs`	Any	关键字参数（类型 `Any`）。The kwargs.

返回Returns ChatResponse | AsyncGenerator[ChatResponse, None]

返回ChatResponse|AsyncGenerator[ChatResponse,None]。Returns chat response async generator chat response none.

源码Source agentscope/model/_base.py:184–300

count_tokens

async def count_tokens(messages: list[Msg], tools: list[dict] | None) -> int

async

执行数量令牌数相关操作。

Note a standard way to count the tokens is first formatting the input messages into the API required format, then use the tokenizer of the underlying API to count the tokens.

参数Parameters

名称Name	类型Type	说明Description
`messages`	list[Msg]	消息到发送到模型。The messages to send to the model.
`tools`	list[dict] \| None	工具可用到模型。The tools available to the model.

返回Returns int

返回数值结果。`int`:

源码Source agentscope/model/_base.py:379–465

generate_structured_output

async def generate_structured_output(messages: list[Msg], structured_model: Type[BaseModel] | dict, **kwargs: Any) -> StructuredResponse

async

执行 generate_structured_output 方法。

Each strategy is retried on transient (retryable) errors.

参数Parameters

名称Name	类型Type	说明Description
`messages`	list[Msg]	消息列表（类型 `list[Msg]`）。The context for LLM to generate the structured output.
`structured_model`	Type[BaseModel] \| dict	结构化模型（类型 `Type[BaseModel] \| dict`）。A Pydantic model or a dict of JSON schemas.
`kwargs`	Any	关键字参数（类型 `Any`）。The kwargs.

返回Returns StructuredResponse

返回StructuredResponse。`StructuredResponse`:

源码Source agentscope/model/_base.py:467–603

嵌套类详情Nested Class Detail

Parameters

class Parameters

参数，与模型服务通信并返回生成或向量化结果。位于 agentscope.model 包。

Each subclass should implement this inner class to define its parameters. Declared in agentscope.model.