> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Neon AI Gateway

> Neon에서 제공하는 OpenAI 호환 Inference 엔드포인트인 Neon AI Gateway에 대한 Call을 트레이스합니다

이 가이드에서는 Weave를 사용하여 Neon AI Gateway에서 서빙되는 모델에 대한 Call을 자동으로 트레이스하는 방법을 설명합니다. 이를 통해 하나의 대시보드에서 모델 사용 현황을 모니터링, 디버그, 평가할 수 있습니다.

[Neon AI Gateway](https://neon.com/docs/ai-gateway/overview)는 Neon에서 제공하는 OpenAI 호환 Inference 엔드포인트입니다. 공급자별 API 키 없이 Neon 자격 증명 하나로 OpenAI, Google, Meta, Databricks, Alibaba의 모델을 사용할 수 있습니다. Weave가 OpenAI SDK를 자동으로 감지하므로 API 키와 base URL만 변경하면 기존 OpenAI 코드를 그대로 사용할 수 있습니다.

<Note>
  Neon AI Gateway는 현재 베타 버전입니다. 사용하려면 선불 크레딧이 충전된 유료 Neon 플랜과 지원되는 AWS 리전의 프로젝트가 필요합니다. 자세한 요구 사항은 [Neon AI Gateway](https://neon.com/docs/ai-gateway/overview)를 참조하세요.
</Note>

<h2 id="prerequisites">
  사전 요구 사항
</h2>

대부분의 공급자와 달리 Neon에는 공통으로 사용하는 단일 호스트 이름이 없습니다. 데이터베이스 브랜치마다 고유한 게이트웨이 호스트가 할당되므로 다음 두 가지 값이 필요합니다.

* `ai_gateway:invoke` 범위가 부여된 **자격 증명**. Neon Console의 **Credentials**에서 생성하거나 Neon API로 생성하세요. 자세한 내용은 [AI Gateway 인증](https://neon.com/docs/ai-gateway/authentication)을 참조하세요.
* Neon Console에 `NEON_AI_GATEWAY_BASE_URL`로 표시되는 **브랜치 호스트**. 브랜치별로 다른
  URL이며 `https://<your-neon-branch-host>` 형식입니다.

`neon env pull --file .env`를 실행하면 두 값이 각각 `NEON_AI_GATEWAY_TOKEN`과 `NEON_AI_GATEWAY_BASE_URL`로 기록됩니다.

<h2 id="trace-a-neon-ai-gateway-call">
  Neon AI Gateway Call 트레이스하기
</h2>

`api_key`에는 Neon 자격 증명을, `base_url`에는 브랜치 호스트 뒤에 `/v1`을 붙인 값을 설정하고, 모델 ID로는 `gpt-5-mini`와 같은 짧은 Neon 모델 ID를 사용하세요. `weave.init()`에는 트레이스를 저장할 프로젝트 이름이 필요합니다. 필요한 경우 `<entity>/<project>` 형식으로 프로젝트 이름 앞에 W\&B entity를 붙일 수 있습니다. entity를 생략하면 Weave는 기본 entity를 사용합니다. 기본 entity를 확인하거나 변경하려면 [기본 팀](/ko/platform/app/settings-page/user-settings/#default-team)을 참고하세요.

```python lines {5,10-13} theme={null}
import os
import openai
import weave

weave.init('neon-weave')

system_content = "You are a travel agent. Be descriptive and helpful."
user_content = "Tell me about San Francisco"

client = openai.OpenAI(
    api_key=os.environ.get("NEON_AI_GATEWAY_TOKEN"),
    base_url=f"{os.environ.get('NEON_AI_GATEWAY_BASE_URL')}/v1",
)
chat_completion = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[
        {"role": "system", "content": system_content},
        {"role": "user", "content": user_content},
    ],
    temperature=0.7,
    max_tokens=1024,
)
response = chat_completion.choices[0].message.content
print("Model response:\n", response)
```

Weave는 이 Call을 프로젝트에 트레이스로 캡처합니다. 트레이스에는 모델 ID, 메시지, Neon이 반환한 토큰 수가 포함됩니다.

<h2 id="trace-across-branches">
  브랜치 간 트레이스
</h2>

Neon 자격 증명은 해당 자격 증명이 생성된 브랜치와 그 브랜치에서 파생된 모든 브랜치에서 유효합니다. 따라서 `main`에서 생성한 자격 증명은 `main`에서 분기한 프리뷰 및 CI 브랜치에서도 사용할 수 있습니다. 환경마다 달라지는 것은 `NEON_AI_GATEWAY_BASE_URL`뿐입니다.

브랜치 호스트는 요청이 아니라 클라이언트 설정에 포함되므로, 서로 다른 브랜치에서 생성된 트레이스도 Weave에서는 똑같이 보입니다. 브랜치별 트레이스를 구분하려면 `weave.init()`에 브랜치마다 다른 프로젝트 이름을 전달하거나, 브랜치 정보를 속성으로 추가하세요.

```python theme={null}
with weave.attributes({"neon_branch": "preview/feature-x"}):
    chat_completion = client.chat.completions.create(
        model="gpt-5-mini",
        messages=[{"role": "user", "content": user_content}],
    )
```

<h2 id="choose-a-model">
  모델 선택하기
</h2>

Neon은 `gpt-5-mini`, `gemini-3-flash`, `llama-4-maverick`, `qwen3-next-80b-a3b-instruct`와 같은 짧은 모델 ID를 사용합니다. 다음과 같이 브랜치에서 서빙할 수 있는 모델 목록을 확인하세요.

```bash theme={null}
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/models" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN"
```

컨텍스트 윈도우와 가격은 [Neon 모델 카탈로그](https://neon.com/docs/ai-gateway/models)에서 확인할 수 있으며, [Models.dev의 `neon` 공급자](https://models.dev/providers/neon/)에도 게시되어 있습니다.

모델 선택에 영향을 주는 제약 조건은 두 가지입니다.

* 일부 모델은 Neon의 Responses API 경로인 `{NEON_AI_GATEWAY_BASE_URL}/openai/v1`에서만 제공되며, Chat Completion 요청에는 `400`을 반환합니다. 해당 모델은 Neon [모델 카탈로그](https://neon.com/docs/ai-gateway/models)의 Endpoints 열에서 확인할 수 있으며, 대상 모델은 변경될 수 있습니다. 이 문서 작성 시점에는 `gpt-5-3-codex`와 `gpt-5-5-pro`가 해당됩니다. 이 열에 `chat/completions`가 표시된 모델은 모두 Chat Completion 경로에서 사용할 수 있습니다.

Neon은 비용 필드를 반환하지 않으며 `GET /v1/models`에서 `pricing`을 `null`로 보고하므로, 트레이스에는 비용 없이 토큰 수만 표시됩니다. AI Gateway 사용량은 선불 크레딧 잔액에서 차감됩니다. 자세한 내용은 [AI Gateway 가격](https://neon.com/docs/ai-gateway/overview#pricing)을 참조하세요.

더 복잡한 사용 사례를 위해 Weave를 자체 함수와 통합하는 방법은 [OpenAI 인테그레이션 가이드](/ko/weave/guides/integrations/openai#track-your-own-ops)를 참조하세요.