Z.AI 모델
Z.AI 모델
Z.AI(지푸 AI)는 GLM 시리즈를 제공하는 모델 제공자예요. pydantic-ai에서 ZaiModel을 사용하면 GLM 모델을 손쉽게 호출할 수 있어요. 이 문서에서 설치부터 thinking 모드, 커스텀 프로바이더 사용법까지 설명할게요.
출처: 문서
본문
설치하기
ZaiModel을 쓰려면 pydantic-ai를 설치하거나, pydantic-ai-slim을 zai 옵션 그룹과 함께 설치하면 돼요.
pip install "pydantic-ai-slim[zai]"
uv add "pydantic-ai-slim[zai]"
구성하기
Z.AI(Zhipu AI)를 API로 사용하려면 z.ai로 가서 API 키를 생성하면 돼요.
사용 가능한 모델 목록은 Z.AI 문서를 확인하세요.
환경 변수
API 키를 확보했다면 환경 변수로 설정할 수 있어요:
export ZAI_API_KEY='your-api-key'
그러면 ZaiModel을 이름으로 사용할 수 있어요:
from pydantic_ai import Agent
agent = Agent('zai:glm-5')
...
아니면 모델 이름만으로 모델을 직접 초기화해도 돼요:
from pydantic_ai import Agent
from pydantic_ai.models.zai import ZaiModel
model = ZaiModel('glm-5')
agent = Agent(model)
...
Thinking 모드
Z.AI의 glm-5.3, glm-5.2, glm-5.1, glm-5, glm-4.7, glm-4.6(하이브리드 thinking), glm-4.5(인터리브드 thinking) 모델은 thinking/reasoning 모드를 지원해요. 모델이 최종 응답 전에 reasoning 콘텐츠를 생성하는 거예요. 여기에는 glm-4.6v와 glm-4.5v 비전 모델도 포함돼요. 통합된 thinking 설정으로 구성하세요:
from pydantic_ai import Agent
from pydantic_ai.settings import ModelSettings
agent = Agent(
'zai:glm-5',
model_settings=ModelSettings(thinking=True),
)
...
thinking=True는 thinking을 활성화하고 thinking=False는 비활성화해요(GLMT-5.3은 항상 reasoning해서 thinking=False를 무시하는데, 그건 제외예요). GLM-5.2와 GLM-5.3에서는 명시적 effort 레벨('minimal'/'low'/'medium'/'high'/'xhigh')이 reasoning_effort로 Z.AI에 전달돼요. GLM-5.3은 low/high/max만 받아들이므로, 다른 레벨은 가장 가까운 것으로 매핑돼요(minimal→low, medium→high, xhigh→max). effort 세분화를 노출하지 않는 다른 GLM 모델에서는 effort 레벨이 모두 활성화(켜짐)로 수렴돼요. 필드를 생략하면 각 모델의 기본 동작을 사용해요.
보존된 thinking
thinking 가능 모델에서는 이전 에이전트 응답의 reasoning 콘텐츠가 기본적으로 보존돼요. 별도 구성이 필요 없어요. 다중 턴 응집력과 다른 프로바이더와의 일관성을 높이기 위해서예요. 이전 턴의 완전하고 수정되지 않은 reasoning_content가 Pydantic AI에 의해 자동으로 API로 다시 전송돼요.
반면 각 턴을 새로 시작하고 싶다면, Z.AI 특유의 ZaiModelSettings로 zai_clear_thinking=True를 설정해서 비활성화하면 돼요:
from pydantic_ai import Agent
from pydantic_ai.models.zai import ZaiModelSettings
agent = Agent(
'zai:glm-5',
# Opt out of the default preserved thinking:
model_settings=ZaiModelSettings(thinking=True, zai_clear_thinking=True),
)
...
자세한 내용은 Z.AI thinking 모드 문서를 참고하세요.
provider 인자
provider 인자를 통해 커스텀 Provider를 제공할 수 있어요. 가장 간단한 경우에는 API 키만으로 ZaiProvider를 전달하면 돼요. 기본 httpx2.AsyncClient를 커스터마이즈하고 싶다면 프로바이더를 만들 때 전달하세요:
from httpx2 import AsyncClient
from pydantic_ai import Agent
from pydantic_ai.models.zai import ZaiModel
from pydantic_ai.providers.zai import ZaiProvider
custom_http_client = AsyncClient(timeout=30)
model = ZaiModel(
'glm-5',
provider=ZaiProvider(api_key='your-api-key', http_client=custom_http_client),
)
agent = Agent(model)
...
커스텀 HTTP 클라이언트가 필요 없다면 http_client=custom_http_client 인자를 생략하면 돼요.