Snowflake Cortex 모델

Snowflake Cortex는 Snowflake 계정 안에서 호스팅되는 REST API를 통해 Claude, GPT, Llama, Mistral, DeepSeek, 그리고 Snowflake 자체 모델을 제공해요. 데이터가 Snowflake 보안 경계를 벗어나지 않는다는 점이 특징이에요. 이 문서에서 pydantic-ai로 Snowflake Cortex 모델을 사용하는 방법을 설명할게요.

출처: 문서

본문

설치하기

Snowflake Cortex는 service_tier를 무시하지 않고 오류로 거부해요. 그래서 Snowflake 모델에서는 그 설정을 비워 두어야 해요. SnowflakeModel을 쓰려면 pydantic-ai를 설치하거나, pydantic-ai-slim을 snowflake 옵션 그룹과 함께 설치하면 돼요.

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

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

구성하기

Snowflake Cortex는 Snowflake 계정 안에서 호스팅되는 REST API를 통해 Claude, GPT, Llama, Mistral, DeepSeek, 그리고 Snowflake 자체 모델을 제공해요. 그래서 데이터가 Snowflake 보안 경계를 벗어나지 않아요.

사용하려면 Snowflake 계정 식별자(예: myorg-myaccount)와 토큰이 필요해요. 토큰은 프로그래매틱 액세스 토큰(PAT), OAuth 토큰, 또는 키-페어 JWT 중 하나예요. 요청이 실행되는 역할(PAT가 제한된 역할, 또는 기본적으로는 사용자의 기본 역할)은 SNOWFLAKE.CORTEX_USER 데이터베이스 역할을 가져야 해요. 이 역할은 기본적으로 PUBLIC에 부여돼요.

사용 가능한 모델 목록은 Cortex REST API 문서를 참고하세요. 파인튜닝된 모델은 database.schema.model 형식으로 참조할 수 있어요.

환경 변수

계정 식별자와 토큰을 확보했다면 환경 변수로 설정할 수 있어요:

export SNOWFLAKE_ACCOUNT='myorg-myaccount'
export SNOWFLAKE_TOKEN='your-token'

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

from pydantic_ai import Agent

agent = Agent('snowflake:claude-sonnet-4-6')
...

아니면 모델 이름만으로 모델을 직접 초기화해도 돼요:

from pydantic_ai import Agent
from pydantic_ai.models.snowflake import SnowflakeModel

model = SnowflakeModel('claude-sonnet-4-6')
agent = Agent(model)
...

`provider` 인자

provider 인자를 통해 커스텀 Provider를 제공할 수 있어요:

from pydantic_ai import Agent
from pydantic_ai.models.snowflake import SnowflakeModel
from pydantic_ai.providers.snowflake import SnowflakeProvider

model = SnowflakeModel(
    'claude-sonnet-4-6',
    provider=SnowflakeProvider(account='myorg-myaccount', token='your-token'),
)
agent = Agent(model)
...

SnowflakeProvider를 커스텀 base_url(예: 프라이빗 커넥티비티로 연결할 때)이나 httpx2.AsyncClient로 커스터마이즈할 수도 있어요:

from httpx2 import AsyncClient

from pydantic_ai import Agent
from pydantic_ai.models.snowflake import SnowflakeModel
from pydantic_ai.providers.snowflake import SnowflakeProvider

model = SnowflakeModel(
    'claude-sonnet-4-6',
    provider=SnowflakeProvider(
        base_url='https://myorg-myaccount.privatelink.snowflakecomputing.com/api/v2/cortex/v1',
        token='your-token',
        http_client=AsyncClient(timeout=30),
    ),
)
agent = Agent(model)
...

모델 기능

Cortex는 OpenAI(openai-*)와 Claude(claude-*) 모델에 대해서만 툴 호출과 구조화된 출력을 지원해요. 다른 모델 계열에서는 구조화된 출력이 프롬프트된 출력으로 폴백돼요.

Thinking

Claude 모델에서 thinking을 활성화하려면 통합된 thinking 모델 설정을 사용하거나, SnowflakeModelSettings.snowflake_reasoning을 직접 설정해 reasoning 토큰 예산을 제어할 수 있어요:

from pydantic_ai import Agent
from pydantic_ai.models.snowflake import SnowflakeModel, SnowflakeModelSettings

agent = Agent(
    SnowflakeModel('claude-sonnet-4-6'),
    model_settings=SnowflakeModelSettings(snowflake_reasoning={'max_tokens': 4096}),
)
...

OpenAI 모델에서는 통합된 thinking 설정이나 openai_reasoning_effort를 사용하세요.

참고

Claude는 thinking이 활성화되면 temperature가 정확히 1이어야 해요. 그런데 Cortex는 요청이 temperature를 지정하지 않을 때 다른 기본값을 적용해요. 그래서 SnowflakeModel은 reasoning이 활성화되고 명시적으로 temperature를 설정하지 않았을 때 temperature를 자동으로 1로 설정해요.

Snowflake Cortex 모델