Cortex Chat Completions API¶

Cortex Chat Completions API는 어떤 모델에서도 사용할 수 있는 OpenAI Chat Completions API의 상위 기능으로, 광범위한 도구, 라이브러리 및 서드 파티 AI 애플리케이션 생태계와의 호환성을 지원합니다.

Cortex Chat Completions API는 OpenAI 모델에 대한 지원을 확장적으로 제공할 수 있는 Cortex REST API에 대한 컴패니언 API입니다. Cortex REST API에 대해 자세히 알아보려면 Cortex REST API 섹션을 참조하세요.

OpenAI SDK 시작¶

중요

`OpenAI 라이브러리 설명서<https://platform.openai.com/docs/libraries>`_에 명시된 공식 버전의 OpenAI SDK를 사용하고 있는지 확인하세요. 예를 들어, 다음 언어 중 하나에서 제공되는 SDK를 사용할 수 있습니다.

Python
TypeScript 또는 JavaScript

시작하려면 다음이 필요합니다.

Snowflake 계정 URL. 이는 OpenAI 클라이언트에 대한 기본 URL을 구성하는 데 사용됩니다.
Snowflake PAT(프로그래밍 방식 액세스 토큰). 이는 Cortex Chat Completions API를 인증하는 데 사용됩니다. PAT 생성에 대한 자세한 내용은 프로그래밍 방식 액세스 토큰 생성하기 섹션을 참조하세요.
요청에서 사용할 유효한 모델 이름입니다. 지원되는 모델 목록은 모델 가용성 섹션을 참조하세요.

간단한 코드 예제¶

다음 예는 Python, JavaScript 또는 TypeScript 및 ``curl``을 사용하여 OpenAI SDKs를 요청하는 방법을 보여줍니다.

다음 코드를 사용하면 Python SDK를 시작하는 데 도움이 됩니다.

from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
)

response = client.chat.completions.create(
model="<model_name>",
messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {
        "role": "user",
        "content": "How does a snowflake get its unique pattern?"
    }
  ]
)

print(response.choices[0].message)

Copy

앞의 코드에서 다음에 대한 값을 지정합니다.

base_url: :code:`<account-identifier>`를 Snowflake 계정 식별자로 바꿉니다.
api_key: :code:`<SNOWFLAKE_PAT>`를 Snowflake PAT(프로그래밍 방식 액세스 토큰)로 바꿉니다.
model: <model_name>`을 사용하려는 모델의 이름으로 바꿉니다. 지원되는 모델 목록은 :ref:`label-cortex_complete_llm_model_availability 섹션을 참조하세요.

다음 코드를 사용하면 JavaScript 또는 TypeScript SDK를 시작하는 데 도움이 됩니다.

import OpenAI from "openai";

const openai = new OpenAI({
  apikey="SNOWFLAKE_PAT",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
});

const response = await openai.chat.completions.create({
  model: "claude-3-7-sonnet",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    {
        role: "user",
        content: "How does a snowflake get its unique pattern?",
    },
  ],
});

console.log(response.choices[0].message);

Copy

앞의 코드에서 다음에 대한 값을 지정합니다.

baseURL: :code:`<account-identifier>`를 Snowflake 계정 식별자로 바꿉니다.
apikey: :code:`SNOWFLAKE_PAT`를 Snowflake PAT(개인 액세스 토큰)로 바꿉니다.
model: <model_name>`을 사용하려는 모델의 이름으로 바꿉니다. 지원되는 모델 목록은 :ref:`label-cortex_complete_llm_model_availability 섹션을 참조하세요.

다음 curl 명령을 사용하여 Snowflake 호스팅 모델에 요청합니다.

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <SNOWFLAKE_PAT>" \
-d '{
  "model": "<model_name>",
  "messages": [
      {"role": "user", "content": "How does a snowflake get its unique pattern?"}
  ]
}'

Copy

앞의 코드에서 다음에 대한 값을 지정합니다.

<account-identifier>: :code:`<account-identifier>`를 Snowflake 계정 식별자로 바꿉니다.
<SNOWFLAKE_PAT>: :code:`<SNOWFLAKE_PAT>`를 Snowflake PAT(개인 액세스 토큰)로 바꿉니다.
<model_name>: <model_name>`을 사용하려는 모델의 이름으로 바꿉니다. 지원되는 모델 목록은 :ref:`label-cortex_complete_llm_model_availability 섹션을 참조하세요.

응답 스트리밍¶

요청에서 stream 매개 변수를 :code:`True`로 설정하여 REST API에서 응답을 스트리밍할 수 있습니다.

다음 Python 코드는 REST API에서 응답을 스트리밍합니다.

from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
)

response = client.chat.completions.create(
  model="<model_name>",
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {
        "role": "user",
        "content": "How does a snowflake get its unique pattern?"
    }
  ],
  stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content, end="", flush=True)

Copy

다음 JavaScript 또는 TypeScript 코드는 REST API에서 응답을 스트리밍합니다.

import OpenAI from "openai";

const openai = new OpenAI({
    apikey="SNOWFLAKE_PAT",
    baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
});

const stream = await openai.chat.completions.create({
    model: "<model_name>",
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      {
          role: "user",
          content: "How does a snowflake get its unique pattern?",
      }
    ],
    stream:true,
});


for await (const event of stream) {
  console.log(event);
}

Copy

다음 curl 명령은 Snowflake 호스팅 모델의 응답을 스트리밍합니다.

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SNOWFLAKE_PAT" \
-d '{
  "model": "<model_name>",
  "messages": [
      {"role": "user", "content": "How does a snowflake get its unique pattern?"}
  ],
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}'

Copy

제한 사항¶

다음은 Snowflake 호스팅 모델에서 OpenAI SDK를 사용할 때의 제한 사항입니다.

Chat Completions만 지원됩니다.
설정 해제할 경우 :code:`max_completion_tokens`의 기본값은 4096입니다. Cortex Chat Completions API의 이론적 최대값은 131,072입니다. 각 모델에는 131,072 미만일 수 있는 자체 출력 토큰 제한이 있습니다.
도구 호출은 OpenAI 및 Claude 모델에 대해 지원됩니다. 도구 호출을 효과적으로 사용하는 예는 사고 체인을 이용한 도구 호출 예제 섹션을 참조하세요.
오디오는 지원되지 않습니다.
이미지 이해는 OpenAI 및 Claude 모델에 대해서만 지원됩니다. 이미지는 20MiB로 최대 요청 크기가 제한되며 대화당 20개로 제한됩니다.
Claude 모델만 프롬프트 캐싱을 위해 임시 캐시 제어 지점을 지원합니다. OpenAI 모델은 암시적 캐싱을 지원합니다.
Claude 모델만 응답에서 추론 세부 정보 반환을 지원합니다.
오류 메시지는 OpenAI가 아닌 Snowflake에서 생성됩니다. 보고된 오류는 로깅 및 디버깅 목적으로만 사용하는 것이 좋습니다.

상세 호환성 차트¶

다음 표에는 다양한 Snowflake 호스팅 모델에서 Cortex Chat Completions API를 사용할 때 지원되는 요청 및 응답 필드와 헤더가 요약되어 있습니다.

요청 필드¶
필드	OpenAI 모델	Claude 모델	기타 모델
`model`	✔ 지원	✔ 지원	✔ 지원
`messages`	하위 필드 참조	하위 필드 참조	하위 필드 참조
`messages[].audio`	❌ 오류	❌ 무시됨	❌ 무시됨
`messages[].role`	✔ 지원	✔ 사용자, 어시스턴트, 시스템만 해당	✔ 사용자, 어시스턴트, 시스템만 해당
`messages[].content` (문자열)	✔ 지원	✔ 지원	✔ 지원
:code:`messages[].content[]`(배열)	하위 필드 참조	하위 필드 참조	하위 필드 참조
`messages[].content[].text`	✔ 지원	✔ 지원	✔ 지원
`messages[].content[].type`	✔ 지원	✔ 지원	✔ 지원
`messages[].content[].image_url`	✔ 지원	✔ 지원	❌ 오류
`messages[].content[].cache_control`	❌ 무시됨	✔ 지원됨(임시만 해당)	❌ 무시됨
`messages[].content[].file`	❌ 오류	❌ 오류	❌ 무시됨
`messages[].content[].input_audio`	❌ 오류	❌ 무시됨	❌ 무시됨
`messages[].content[].refusal`	✔ 지원	❌ 무시됨	❌ 무시됨
`messages[].function_call`	✔ 지원됨(사용되지 않음)	❌ 무시됨	❌ 무시됨
`messages[].name`	✔ 지원	❌ 무시됨	❌ 무시됨
`messages[].refusal`	✔ 지원	❌ 무시됨	❌ 무시됨
`messages[].tool_call_id`	✔ 지원	✔ 지원	❌ 무시됨
`messages[].tool_calls`	✔ 지원	✔ `function` 도구만	❌ 무시됨
`messages[].reasoning_details`	❌ 무시됨	✔ OpenRouter 형식 `reasoning.text`	❌ 무시됨
`audio`	❌ 오류	❌ 무시됨	❌ 무시됨
`frequency_penalty`	✔ 지원	❌ 무시됨	❌ 무시됨
`logit_bias`	✔ 지원	❌ 무시됨	❌ 무시됨
`logprobs`	✔ 지원	❌ 무시됨	❌ 무시됨
`max_tokens`	❌ 오류(사용 중단됨)	❌ 오류(사용 중단됨)	❌ 오류(사용 중단됨)
`max_completion_tokens`	✔ 지원됨(기본값 4096, 최대 131072)	✔ 지원됨(기본값 4096, 최대 131072)	✔ 지원됨(기본값 4096, 최대 131072)
`metadata`	❌ 무시됨	❌ 무시됨	❌ 무시됨
`modalities`	❌ 무시됨	❌ 무시됨	❌ 무시됨
`n`	✔ 지원	❌ 무시됨	❌ 무시됨
`parallel_tool_calls`	✔ 지원	❌ 무시됨	❌ 무시됨
`prediction`	✔ 지원	❌ 무시됨	❌ 무시됨
`presence_penalty`	✔ 지원	❌ 무시됨	❌ 무시됨
`prompt_cache_key`	✔ 지원	❌ 무시됨	❌ 무시됨
`reasoning_effort`	✔ 지원	❌ 무시됨(`reasoning` 오브젝트 사용)	❌ 무시됨
`reasoning`	하위 필드 참조	하위 필드 참조	하위 필드 참조
`reasoning.effort`	✔ 지원됨(`reasoning_effort` 재정의)	✔ :code:`reasoning.max_tokens`로 변환됨	❌ 무시됨
`reasoning.max_tokens`	❌ 무시됨	✔ 지원	❌ 무시됨
`response_format`	✔ 지원	✔ Only `json_schema`	❌ 무시됨
`safety_identifier`	❌ 무시됨	❌ 무시됨	❌ 무시됨
`service_tier`	❌ 오류	❌ 오류	❌ 오류
`stop`	✔ 지원	❌ 무시됨	❌ 무시됨
`store`	❌ 오류	❌ 오류	❌ 오류
`stream`	✔ 지원	✔ 지원	✔ 지원
`stream_options`	하위 필드 참조	하위 필드 참조	하위 필드 참조
`stream_options.include_obfuscation`	❌ 무시됨	❌ 무시됨	❌ 무시됨
`stream_options.include_usage`	✔ 지원	✔ 지원	✔ 지원
`temperature`	✔ 지원	✔ 지원	✔ 지원
`tool_choice`	✔ 지원	✔ `function` 도구만	❌ 무시됨
`tools`	✔ 지원	✔ `function` 도구만	❌ 오류
`top_logprobs`	✔ 지원	❌ 무시됨	❌ 무시됨
`top_p`	✔ 지원	✔ 지원	✔ 지원
`verbosity`	✔ 지원	❌ 무시됨	❌ 무시됨
`web_search_options`	❌ 오류	❌ 무시됨	❌ 무시됨

응답 필드¶
필드	OpenAI 모델	Claude 모델	기타 모델
`id`	✔ 지원	✔ 지원	✔ 지원
`object`	✔ 지원	✔ 지원	✔ 지원
`created`	✔ 지원	✔ 지원	✔ 지원
`model`	✔ 지원	✔ 지원	✔ 지원
`choices`	하위 필드 참조	하위 필드 참조	하위 필드 참조
`choices[].index`	✔ 지원	✔ 단일 선택 항목만	✔ 단일 선택 항목만
`choices[].finish_reason`	✔ 지원	❌ 지원되지 않음	✔ :code:`stop`만 해당
`choices[].logprobs`	✔ 지원	❌ 지원되지 않음	❌ 지원되지 않음
:code:`choices[].message`(비스트리밍)	하위 필드 참조	하위 필드 참조	하위 필드 참조
`choices[].message.content`	✔ 지원	✔ 지원	✔ 지원
`choices[].message.role`	✔ 지원	✔ 지원	✔ 지원
`choices[].message.refusal`	✔ 지원	❌ 지원되지 않음	❌ 지원되지 않음
`choices[].message.annotations`	❌ 지원되지 않음	❌ 지원되지 않음	❌ 지원되지 않음
`choices[].message.audio`	❌ 지원되지 않음	❌ 지원되지 않음	❌ 지원되지 않음
`choices[].message.function_call`	✔ 지원	❌ 지원되지 않음	❌ 지원되지 않음
`choices[].message.tool_calls`	✔ 지원	✔ `function` 도구만	❌ 지원되지 않음
`choices[].message.reasoning`	❌ 지원되지 않음	✔ OpenRouter 형식	❌ 지원되지 않음
:code:`choices[].delta`(스트리밍)	하위 필드 참조	하위 필드 참조	하위 필드 참조
`choices[].delta.content`	✔ 지원	✔ 지원	✔ 지원
`choices[].delta.role`	✔ 지원	❌ 지원되지 않음	❌ 지원되지 않음
`choices[].delta.refusal`	✔ 지원	❌ 지원되지 않음	❌ 지원되지 않음
`choices[].delta.function_call`	✔ 지원	❌ 지원되지 않음	❌ 지원되지 않음
`choices[].delta.tool_calls`	✔ 지원	✔ `function` 도구만	❌ 지원되지 않음
`choices[].delta.reasoning`	❌ 지원되지 않음	✔ OpenRouter 형식	❌ 지원되지 않음
`usage`	하위 필드 참조	하위 필드 참조	하위 필드 참조
`usage.prompt_tokens`	✔ 지원	✔ 지원	✔ 지원
`usage.completion_tokens`	✔ 지원	✔ 지원	✔ 지원
`usage.total_tokens`	✔ 지원	✔ 지원	✔ 지원
`usage.prompt_tokens_details`	하위 필드 참조	하위 필드 참조	하위 필드 참조
`usage.prompt_tokens_details.audio_tokens`	❌ 지원되지 않음	❌ 지원되지 않음	❌ 지원되지 않음
`usage.prompt_tokens_details.cached_tokens`	✔ 캐시 읽기만	✔ 캐시 읽기 + 쓰기	❌ 지원되지 않음
`usage.completion_tokens_details`	하위 필드 참조	하위 필드 참조	하위 필드 참조
`usage.completion_tokens_details.accepted_prediction_tokens`	✔ 지원	❌ 지원되지 않음	❌ 지원되지 않음
`usage.completion_tokens_details.audio_tokens`	❌ 지원되지 않음	❌ 지원되지 않음	❌ 지원되지 않음
`usage.completion_tokens_details.reasoning_tokens`	✔ 지원	❌ 지원되지 않음	❌ 지원되지 않음
`usage.completion_tokens_details.rejected_prediction_tokens`	✔ 지원	❌ 지원되지 않음	❌ 지원되지 않음
`service_tier`	✔ 지원	❌ 지원되지 않음	❌ 지원되지 않음
`system_fingerprint`	✔ 지원	❌ 지원되지 않음	❌ 지원되지 않음

헤더 요청¶
헤더	지원
`Authorization`	✔ 필수
`Content-Type`	✔ 지원됨(`application/json`)
`Accept`	✔ 지원됨(`application/json`, `text/event-stream`)

응답 헤더¶
헤더	지원
`openai-organization`	❌ 지원되지 않음
`openai-version`	❌ 지원되지 않음
`openai-processing-ms`	❌ 지원되지 않음
`x-ratelimit-limit-requests`	❌ 지원되지 않음
`x-ratelimit-limit-tokens`	❌ 지원되지 않음
`x-ratelimit-remaining-requests`	❌ 지원되지 않음
`x-ratelimit-remaining-tokens`	❌ 지원되지 않음
`x-ratelimit-reset-requests`	❌ 지원되지 않음
`x-ratelimit-reset-tokens`	❌ 지원되지 않음
`retry-after`	❌ 지원되지 않음

자세히 알아보기¶

사용 예의 전체 개요는 `OpenAI의 Chat Completions API 참조<https://platform.openai.com/docs/guides/completions/>`_ 또는 `OpenAI Cookbook<https://cookbook.openai.com/>`_을 참조하세요.

Snowflake는 Chat Completions API와의 호환성을 제공할 뿐만 아니라 Claude 모델에 대한 OpenRouter 호환 기능도 지원합니다. 이러한 기능은 요청 시 추가 필드로 노출됩니다.

프롬프트 캐싱의 경우 cache_control 필드를 사용합니다. 자세한 내용은 `OpenRouter 프롬프트 캐싱 설명서<https://openrouter.ai/docs/features/prompt-caching>`_를 참조하세요.
추론 토큰의 경우 reasoning 필드를 사용합니다. 자세한 내용은 `OpenRouter 추론 설명서<https://openrouter.ai/docs/use-cases/reasoning-tokens>`_를 참조하세요.