xAI 모델

xAI 모델

xAI는 Grok 시리즈를 제공하는 모델 제공자(프로바이더)예요. pydantic-ai에서 XaiModel을 사용하면 xAI의 모델을 손쉽게 호출할 수 있는데, 이 문서에서 설치부터 이미지 생성, X 검색, 파일 첨부, 멀티 에이전트 모델까지 자세히 설명할게요.

출처: 문서

본문

설치하기

XaiModel을 쓰려면 pydantic-ai를 설치하거나, pydantic-ai-slim을 xai 옵션 그룹과 함께 설치하면 돼요.

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

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

구성하기

xAI의 API를 통해 xAI 모델을 사용하려면 console.x.ai로 가서 API 키를 만들어야 해요.

docs.x.ai에서 사용 가능한 xAI 모델 목록을 확인할 수 있어요.

환경 변수

API 키를 확보했다면 환경 변수로 설정할 수 있어요:

export XAI_API_KEY='your-api-key'

그러면 XaiModel을 이름으로 사용할 수 있어요:

from pydantic_ai import Agent

agent = Agent('xai:grok-4.3')
...

아니면 모델을 직접 초기화해도 돼요:

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModel

# Uses XAI_API_KEY environment variable
model = XaiModel('grok-4.3')
agent = Agent(model)
...

XaiModel을 커스텀 프로바이더로 커스터마이즈할 수도 있어요:

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModel
from pydantic_ai.providers.xai import XaiProvider

# Custom API key
provider = XaiProvider(api_key='your-api-key')
model = XaiModel('grok-4.3', provider=provider)
agent = Agent(model)
...

게이트웨이, 리전, 프록시 배포를 위해 프로바이더를 커스텀 호스트로 지정하고 클라이언트 수준의 기본 타임아웃을 설정할 수도 있어요. 둘 다 기본 xai_sdk.AsyncClient로 전달돼요:

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModel
from pydantic_ai.providers.xai import XaiProvider

provider = XaiProvider(
    api_key='your-api-key',
    api_host='gateway.example.com',
    timeout=30,
)
model = XaiModel('grok-4.3', provider=provider)
agent = Agent(model)
...

api_host는 xAI API 서버의 호스트네임이고(SDK는 gRPC로 연결돼요), timeout은 클라이언트가 만드는 모든 요청에 적용되는 기본 타임아웃(초)이에요. 다른 프로바이더와 달리 xAI SDK는 요청별 타임아웃을 지원하지 않아서, ModelSettings.timeout은 지원되지 않고 효과가 없어요. 두 옵션 모두 설정하지 않으면 생략되어 SDK의 기본값이 적용돼요.

클라이언트가 만드는 모든 요청에 gRPC metadata를 첨부할 수도 있어요. 대표적인 용도는 xAI 프롬프트 캐시 스티키 라우팅이에요. x-grok-conv-id를 통해 대화를 캐시 노드에 고정해서 반복되는 프리픽스가 재처리되는 대신 캐시에서 서빙되게 해요:

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModel
from pydantic_ai.providers.xai import XaiProvider

provider = XaiProvider(
    api_key='your-api-key',
    metadata=(('x-grok-conv-id', 'my-conversation-id'),),
)
model = XaiModel('grok-4.3', provider=provider)
agent = Agent(model)
...

metadata는 (key, value) 문자열 튜플의 시퀀스로, 기본 xai_sdk.AsyncClient에 그대로 전달돼요. 따라서 캐시 히트 최대화에 관한 xAI SDK 자체 문서가 적용돼요. 클라이언트 스코프이기 때문에 프로바이더를 통한 모든 요청에 적용돼요. 고정된 x-grok-conv-id로 구성된 프로바이더를 서로 무관한 대화 사이에 공유하면 안 돼요. 그러면 그 대화들이 같은 캐시 노드에서 충돌할 수 있거든요. 메타데이터가 대화별로 다를 때는 대화마다 별도 프로바이더를 사용하세요. api_host와 timeout처럼 설정하지 않으면 생략되고, 커스텀 xai_sdk.AsyncClient가 전달되면 무시돼요.

또는 커스텀 xai_sdk.AsyncClient를 사용할 수도 있어요:

from xai_sdk import AsyncClient

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModel
from pydantic_ai.providers.xai import XaiProvider

xai_client = AsyncClient(api_key='your-api-key')
provider = XaiProvider(xai_client=xai_client)
model = XaiModel('grok-4.3', provider=provider)
agent = Agent(model)
...

이미지 생성

ImageGenerator를 xai: 이미지 모델과 함께 사용하면 공식 xAI SDK를 통해 직접 생성 및 참조 이미지 편집을 할 수 있어요:

from pydantic_ai import ImageGenerator
from pydantic_ai.images.xai import XaiImageGenerationSettings

generator = ImageGenerator(
    'xai:grok-imagine-image',
    settings=XaiImageGenerationSettings(aspect_ratio='16:9', xai_resolution='1k'),
)

xAI는 인라인 또는 원격 참조 이미지와, UploadedFile로 표현되는 xAI Files API ID를 받아들여요. 혼합 참조 입력은 SDK가 시퀀스를 재정렬하도록 요구하면 안 돼요. 공통 API와 지오메트리 동작은 이미지 생성 가이드를 참고하세요.

중재된 이미지

xAI는 조용히 중재해요. 이미지를 플래그하면 요청은 여전히 성공하고 플래그된 슬롯은 오류 대신 비어서 돌아와요. Pydantic AI는 플래그되지 않은 이미지를 반환하므로, 플래그된 이미지 하나가 요금을 청구한 배치의 나머지를 버리지 않아요. 플래그된 위치는 provider_details['moderated_image_indices']로 보고돼요.

그 키는 xAI가 플래그한 배치 내 0기반 위치를 담아요. 이미지가 하나 이상 플래그됐을 때만 존재하므로, len(result.images)에 플래그된 위치 수를 더하면 요청한 xai_n이 돼요. 모든 이미지가 플래그됐을 때만 반환할 결과가 없으므로 ContentFilterError가 발생해요.

X 검색

xAI 모델은 실시간 게시물과 콘텐츠를 위해 X(구 Twitter) 검색을 지원해요. 활성화하는 권장 방법은 XSearch 기능을 사용하는 거예요. 크로스 프로바이더 사용을 포함한 자세한 내용은 기능 문서를 참고하세요. 지원되는 옵션 전체 목록은 xAI X Search 문서를 확인하세요.

from datetime import datetime

from pydantic_ai import Agent
from pydantic_ai.capabilities import XSearch

agent = Agent(
    'xai:grok-4.3',
    capabilities=[
        XSearch(
            allowed_x_handles=['OpenAI', 'AnthropicAI', 'dasfacc'],
            from_date=datetime(2024, 1, 1),
            to_date=datetime(2024, 12, 31),
            enable_image_understanding=True,
            enable_video_understanding=True,
            include_output=True,
        )
    ],
)

result = agent.run_sync('What have AI companies been posting about?')
print(result.output)
"""
OpenAI announced their latest model updates, while Anthropic shared research on AI safety...
"""

(이 예제는 완전해서 "그대로" 실행할 수 있어요)

XSearch 기능이 받아들이는 옵션은 다음과 같아요:

  • allowed_x_handles / excluded_x_handles: 최대 20개의 X 핸들로 결과를 필터링해요(또는 제외해요). 이 둘은 상호 배타적이에요.
  • from_date / to_date: 주어진 datetime 범위 내에서 생성된 게시물로 결과를 제한해요(naive datetime은 UTC로 해석돼요).
  • enable_image_understanding(기본: False): 게시물에 첨부된 이미지를 분석해요.
  • enable_video_understanding(기본: False): 게시물에 첨부된 비디오 콘텐츠를 분석해요.
  • include_output(기본: False): ModelResponse.native_tool_calls로 사용 가능한 NativeToolReturnPart에 원시 X 검색 결과를 포함해요. 이 옵션이 없으면 모델은 검색 결과를 내부적으로 쓰고 텍스트 요약만 반환해요. 활성화하면 검색된 게시물, 소스, 메타데이터에 프로그래매틱하게 접근할 수 있어요.

기능의 대안으로, capabilities=[NativeTool(XSearchTool(...))]를 통해 저수준 XSearchTool을 직접 전달할 수 있어요(X Search Tool 문서 참고). 또는 XaiModelSettings.xai_include_x_search_output 모델 설정을 통해 원시 출력을 전역으로 활성화할 수 있어요.

파일 첨부

사용자 프롬프트에 문서를 포함하면 xAI는 지원되는 에이전틱 모델에서 자동으로 attachment_search 툴을 사용 가능하게 해요. 모델이 그 툴을 사용하면 Pydantic AI는 그 라이프사이클을 모델의 응답과 함께 노출해요. xAI는 파일 하나를 48 MB로 제한해요. 지원되는 입력 형태는 문서 입력을 참고하세요.

NativeToolCallPart와 NativeToolReturnPart는 tool_name이 'attachment_search'예요. 호출의 provider_details['function_name']은 xAI가 실행한 작업의 이름(예: 'pdf_browse')을 담아요. XaiModelSettings.xai_include_attachment_search_output을 True로 설정하면 xAI가 검색된 콘텐츠를 NativeToolReturnPart에 포함하도록 요청해요. 기본값은 False라서, 활성화하지 않으면 이 옵션이 전송되지 않아요.

첨부 검색은 대화에 직접 첨부된 파일에 적용돼요. 영구적 xAI 컬렉션을 검색하려면 FileSearchTool을 사용하세요.

Reasoning effort

Grok 4.3은 reasoning_effort 값으로 'none', 'low', 'medium', 'high'를 지원해요. XaiModelSettings.xai_reasoning_effort로 직접 구성하거나, 크로스 프로바이더 ModelSettings.thinking 설정을 사용할 수 있어요:

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModelSettings

agent = Agent(
    'xai:grok-4.3',
    model_settings=XaiModelSettings(xai_reasoning_effort='medium'),
)

Grok 4.3에서 reasoning을 비활성화하려면 xai_reasoning_effort='none' 또는 thinking=False를 설정하세요. xAI는 몇몇 퇴역 텍스트 모델 슬러그를 grok-4.3으로 리다이렉트해요. 예측 가능한 동작과 비용이 필요할 때는 grok-4.3과 명시적 reasoning effort를 선택하세요. 자세한 내용은 xAI May 15 retirement 가이드를 참고하세요.

Grok 4.5는 'low', 'medium', 'high'는 지원하지만 'none'은 지원하지 않아서 항상 reasoning을 해요. thinking=False는 조용히 무시되고 thinking=True는 'medium'으로 매핑돼요.

에이전틱 턴

요청이 xAI의 서버 측 네이티브 툴(예: 웹 검색, 코드 실행, X 검색)을 사용하면, xAI가 최종 응답을 반환하기 전에 자체 루프를 실행해요. 그 툴을 호출하고 결과를 처리하는 거죠. 서버 측 루프가 취할 수 있는 턴 수는 XaiModelSettings.xai_max_turns로 제한할 수 있어요:

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModelSettings

agent = Agent(
    'xai:grok-4.3',
    model_settings=XaiModelSettings(xai_max_turns=5),
)

xai_max_turns는 xAI의 서버 측 네이티브 툴 루프만 제어해요. 일반 클라이언트 측 툴이나 Pydantic AI 자체 에이전트 루프에는 효과가 없어요. 그것들을 제한하려면 UsageLimits를 사용하세요.

병렬 툴 호출이 활성화되면 단일 턴 내에서 여러 툴 호출이 발생할 수 있으므로, xai_max_turns가 만들어진 총 툴 호출 수와 반드시 같지는 않다는 점에 유의하세요.

멀티 에이전트 모델

xAI의 멀티 에이전트 모델(예: grok-4.20-multi-agent)은 답변하기 전에 여러 에이전트가 병렬로 질문을 조사해요. XaiModelSettings.xai_agent_count로 사용할 에이전트 수를 선택할 수 있는데, 4 또는 16을 받아요:

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModelSettings

agent = Agent(
    'xai:grok-4.20-multi-agent',
    model_settings=XaiModelSettings(xai_agent_count=16),
)

에이전트 수가 많을수록 더 깊은 조사가 가능하지만, 토큰과 지연 시간이 더 들어요. 다른 xAI 모델은 이 설정을 무시해요.

스트리밍 취소

Transport 취소

cancel()은 다른 작업에서 실행 중인 것을 포함해 활성 로컬 스트림 풀을 안전하게 중단해요. 현재 xai-sdk 릴리스는 그 취소를 사용해 활성 gRPC 읽기를 취소하지만, SDK는 문서화된 스트림별 RPC 핸들을 노출하지 않아요. 따라서 로컬 이터레이터가 닫힌 후 원격 생성이나 청구가 언제 멈출지는 보장하지 않아요. xai-org/xai-sdk-python#142 참고하세요.

더 알아보기 (Learn more)