모델 ID 해석
모델 ID 해석 (Resolve Model ID)
ResolveModelId는 애플리케이션 특정 모델 ID를 Model 인스턴스로 바꿔 주는 캐퍼빌리티예요. 해석기(resolver)는 런 의존성을 사용해 테넌트별 공급자, 자격 증명, 모델 레지스트리를 조회할 수 있습니다.
출처: 문서
본문
from dataclasses import dataclass
from typing import Any
from pydantic_ai import Agent, ModelResolutionContext
from pydantic_ai.capabilities import ResolveModelId
from pydantic_ai.models import Model, infer_model
from pydantic_ai.providers import Provider, infer_provider
from pydantic_ai.providers.openai import OpenAIProvider
@dataclass
class Deps:
"""Per-user provider credentials."""
openai_api_key: str
def resolve_model(ctx: ModelResolutionContext[Deps], model_id: str) -> Model | None:
"""Resolve IDs in the `user:` namespace with the current user's credentials."""
if not model_id.startswith('user:'):
return None
def provider_factory(provider_name: str) -> Provider[Any]:
if provider_name == 'openai':
return OpenAIProvider(api_key=ctx.deps.openai_api_key)
return infer_provider(provider_name)
return infer_model(model_id.removeprefix('user:'), provider_factory)
agent = Agent(
'user:openai:gpt-5.6-sol',
deps_type=Deps,
capabilities=[ResolveModelId(resolve_model)],
)
실시간(realtime) 세션은 이 캐퍼빌리티가 아니라 호출마다 모델을 가져오므로, 같은 종류의 팩토리를 대신 infer_realtime_model()에 전달하세요: agent.realtime(infer_realtime_model('openai:gpt-realtime', provider_factory=...)).
해석기는 동기 또는 비동기일 수 있어요. 전체 callable 시그니처는 (ModelResolutionContext[Deps], str) -> Model | None | Awaitable[Model | None]입니다. 편의 캐퍼빌리티는 두 형태 모두 비동기 resolve_model_id() 훅에 맞춥니다.
해석기들은 캐퍼빌리티 순서대로 체인을 이룹니다. 첫 번째 None이 아닌 결과가 이기고, 모든 해석기가 None을 반환하면 Pydantic AI는 일반 모델 추론으로 폴백해요. 커스텀 캐퍼빌리티에서 훅을 구현하고 각 해석기 트리가 언제 사용되는지 이해하려면 Resolving model IDs를 보세요.
지속 실행 (Durable execution)
지속 실행 (Temporal, DBOS, Prefect)에서는 해석기가 activity/step/task 안에서 다시 실행되어 워커에서 모델을 재구성하므로, 주어진 (model_id, deps)에 대해 결정적이어야 하고 외부 I/O를 수행하면 안 됩니다 — 자격 증명과 레지스트리 데이터는 deps에 담아 전달하세요.