Neon AI Gateway

이 가이드에서는 Weave를 사용하여 Neon AI Gateway에서 서빙되는 모델에 대한 Call을 자동으로 트레이스하는 방법을 설명합니다. 이를 통해 하나의 대시보드에서 모델 사용 현황을 모니터링, 디버그, 평가할 수 있습니다. Neon AI Gateway는 Neon에서 제공하는 OpenAI 호환 Inference 엔드포인트입니다. 공급자별 API 키 없이 Neon 자격 증명 하나로 OpenAI, Google, Meta, Databricks, Alibaba의 모델을 사용할 수 있습니다. Weave가 OpenAI SDK를 자동으로 감지하므로 API 키와 base URL만 변경하면 기존 OpenAI 코드를 그대로 사용할 수 있습니다.

Neon AI Gateway는 현재 베타 버전입니다. 사용하려면 선불 크레딧이 충전된 유료 Neon 플랜과 지원되는 AWS 리전의 프로젝트가 필요합니다. 자세한 요구 사항은 Neon AI Gateway를 참조하세요.

사전 요구 사항

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

ai_gateway:invoke 범위가 부여된 자격 증명. Neon Console의 Credentials에서 생성하거나 Neon API로 생성하세요. 자세한 내용은 AI Gateway 인증을 참조하세요.
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로 기록됩니다.

Neon AI Gateway Call 트레이스하기

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

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이 반환한 토큰 수가 포함됩니다.

브랜치 간 트레이스

Neon 자격 증명은 해당 자격 증명이 생성된 브랜치와 그 브랜치에서 파생된 모든 브랜치에서 유효합니다. 따라서 main에서 생성한 자격 증명은 main에서 분기한 프리뷰 및 CI 브랜치에서도 사용할 수 있습니다. 환경마다 달라지는 것은 NEON_AI_GATEWAY_BASE_URL뿐입니다. 브랜치 호스트는 요청이 아니라 클라이언트 설정에 포함되므로, 서로 다른 브랜치에서 생성된 트레이스도 Weave에서는 똑같이 보입니다. 브랜치별 트레이스를 구분하려면 weave.init()에 브랜치마다 다른 프로젝트 이름을 전달하거나, 브랜치 정보를 속성으로 추가하세요.

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

모델 선택하기

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

curl "${NEON_AI_GATEWAY_BASE_URL}/v1/models" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN"

컨텍스트 윈도우와 가격은 Neon 모델 카탈로그에서 확인할 수 있으며, Models.dev의 neon 공급자에도 게시되어 있습니다. 모델 선택에 영향을 주는 제약 조건은 두 가지입니다.

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

Neon은 비용 필드를 반환하지 않으며 GET /v1/models에서 pricing을 null로 보고하므로, 트레이스에는 비용 없이 토큰 수만 표시됩니다. AI Gateway 사용량은 선불 크레딧 잔액에서 차감됩니다. 자세한 내용은 AI Gateway 가격을 참조하세요. 더 복잡한 사용 사례를 위해 Weave를 자체 함수와 통합하는 방법은 OpenAI 인테그레이션 가이드를 참조하세요.

시작하기

가이드

쿡북

레퍼런스

세부 정보 및 지원

사전 요구 사항

Neon AI Gateway Call 트레이스하기

브랜치 간 트레이스

모델 선택하기

​사전 요구 사항

​Neon AI Gateway Call 트레이스하기

​브랜치 간 트레이스

​모델 선택하기

사전 요구 사항

Neon AI Gateway Call 트레이스하기

브랜치 간 트레이스

모델 선택하기