跳转到内容

直接模型请求

direct 模块提供了用于向 LLM 发出命令式请求的底层方法，其中唯一的抽象是输入和输出模式的转换，使您能够使用相同的 API 来操作所有模型。

这些方法是 Model 实现的轻量级封装，当您不需要 Agent 的全部功能时，它们提供了一个更简单的接口。

提供了以下函数：

基础示例

这里有一个简单的示例，演示如何使用 direct API 发起一个基本请求：

direct_basic.py
from pydantic_ai.direct import model_request_sync
from pydantic_ai.messages import ModelRequest

# Make a synchronous request to the model
model_response = model_request_sync(
    'anthropic:claude-3-5-haiku-latest',
    [ModelRequest.user_text_prompt('What is the capital of France?')]
)

print(model_response.parts[0].content)
#> The capital of France is Paris.
print(model_response.usage)
#> RequestUsage(input_tokens=56, output_tokens=7)

（这个例子是完整的，可以“按原样”运行）

带工具调用的高级示例

您还可以使用 direct API 来处理函数/工具调用。

即使在这里，我们也可以使用 Pydantic 来为工具生成 JSON 模式。

from typing import Literal

from pydantic import BaseModel

from pydantic_ai import ToolDefinition
from pydantic_ai.direct import model_request
from pydantic_ai.messages import ModelRequest
from pydantic_ai.models import ModelRequestParameters


class Divide(BaseModel):
    """Divide two numbers."""

    numerator: float
    denominator: float
    on_inf: Literal['error', 'infinity'] = 'infinity'


async def main():
    # Make a request to the model with tool access
    model_response = await model_request(
        'openai:gpt-4.1-nano',
        [ModelRequest.user_text_prompt('What is 123 / 456?')],
        model_request_parameters=ModelRequestParameters(
            function_tools=[
                ToolDefinition(
                    name=Divide.__name__.lower(),
                    description=Divide.__doc__,
                    parameters_json_schema=Divide.model_json_schema(),
                )
            ],
            allow_text_output=True,  # Allow model to either use tools or respond directly
        ),
    )
    print(model_response)
    """
    ModelResponse(
        parts=[
            ToolCallPart(
                tool_name='divide',
                args={'numerator': '123', 'denominator': '456'},
                tool_call_id='pyd_ai_2e0e396768a14fe482df90a29a78dc7b',
            )
        ],
        usage=RequestUsage(input_tokens=55, output_tokens=7),
        model_name='gpt-4.1-nano',
        timestamp=datetime.datetime(...),
    )
    """

（此示例是完整的，可以“按原样”运行——您需要添加 asyncio.run(main()) 来运行 main）

何时使用 direct API 与 Agent

在以下情况下，direct API 是理想的选择：

  1. 您需要对模型交互进行更直接的控制
  2. 您希望围绕模型请求实现自定义行为
  3. 您正在模型交互之上构建自己的抽象层

对于大多数应用场景，更高级别的 Agent API 提供了一个更便捷的接口，并附带了额外的功能，如内置的工具执行、重试、结构化输出解析等。

OpenTelemetry 或 Logfire 监测

与 agents 一样，您只需添加几行代码即可启用 OpenTelemetry/Logfire 监测：

direct_instrumented.py
import logfire

from pydantic_ai.direct import model_request_sync
from pydantic_ai.messages import ModelRequest

logfire.configure()
logfire.instrument_pydantic_ai()

# Make a synchronous request to the model
model_response = model_request_sync(
    'anthropic:claude-3-5-haiku-latest',
    [ModelRequest.user_text_prompt('What is the capital of France?')],
)

print(model_response.parts[0].content)
#> The capital of France is Paris.

（这个例子是完整的，可以“按原样”运行）

您也可以在每次调用时单独启用 OpenTelemetry：

direct_instrumented.py
import logfire

from pydantic_ai.direct import model_request_sync
from pydantic_ai.messages import ModelRequest

logfire.configure()

# Make a synchronous request to the model
model_response = model_request_sync(
    'anthropic:claude-3-5-haiku-latest',
    [ModelRequest.user_text_prompt('What is the capital of France?')],
    instrument=True
)

print(model_response.parts[0].content)
#> The capital of France is Paris.

更多详情请参阅调试与监控，包括如何在不使用 Logfire 的情况下使用纯 OpenTelemetry 进行监测。