Z.AI

Z.AI (지푸 AI)

Z.AI(지푸 AI)의 GLM 모델을 쓰려면 ZaiModel을 쓰면 돼요. 설치하고 API 키를 환경 변수로 설정한 뒤 이름으로 바로 에이전트를 만들 수 있어요. 특이한 점은 thinking/추론 모드를 지원한다는 것과, 이전 턴의 reasoning 콘텐츠가 기본적으로 보존된다는 거예요.

출처: 공식문서

설치

ZaiModel을 쓰려면 pydantic-ai를 설치하거나 pydantic-ai-slim을 zai 옵션 그룹과 함께 설치해야 해요.

Terminal

pip install "pydantic-ai-slim[zai]"

Terminal

uv add "pydantic-ai-slim[zai]"

설정

Z.AI(Zhipu AI) API를 쓰려면 z.ai에 가서 API 키를 생성해요.

사용 가능한 모델 목록은 Z.AI 문서를 보세요.

환경 변수

API 키를 받았으면 환경 변수로 설정해요.

Terminal

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(hybrid thinking), glm-4.5(interleaved thinking) 모델은 thinking/추론 모드를 지원해요. 최종 응답 전에 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는 끄는데, 항상 추론하고 thinking=False를 무시하는 GLM-5.3은 예외예요. GLM-5.2·GLM-5.3에서는 명시적 노력 수준('minimal'/'low'/'medium'/'high'/'xhigh')이 reasoning_effort로 Z.AI에 전달돼요. GLM-5.3은 low/high/max만 받으므로 나머지 수준은 가장 가까운 것으로 매핑돼요(minimal→low, medium→high, xhigh→max). 노력 세분화를 노출하지 않는 다른 GLM 모델에서는 노력 수준이 모두 enabled로 합쳐져요. 필드를 생략하면 각 모델의 기본 동작을 써요.

보존된 thinking

thinking 가능 모델에서 이전 어시스턴트 응답의 reasoning 콘텐츠는 기본적으로 보존돼요. 구성이 필요 없죠. 더 나은 멀티턴 일관성과 다른 provider와의 일관성을 위한 거예요. 이전 턴의 완전하고 수정되지 않은 reasoning_content가 PydanticAI에 의해 자동으로 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 mode 문서를 보세요.

provider 인자

provider 인자로 커스텀 Provider를 제공할 수 있어요. 가장 간단한 경우 API 키만 있는 ZaiProvider를 넘기면 돼요. 기본 httpx2.AsyncClient도 커스터마이즈하고 싶다면 provider를 만들 때 넘기세요.

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 인자는 빼면 돼요.

더 알아보기 (Learn more)

• Z.AI thinking mode 문서 — 모델별 thinking 동작과 보존된 thinking
• Z.AI 문서 — 모델 목록