EvoLink에서 Gemini 3.8 Flash 사용하기: 프로덕션 연동 가이드

빠른 시작

curl https://direct.evolink.ai/v1/chat/completions \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [
      {"role": "user", "content": "Return three rollout risks for an AI API migration."}
    ],
    "max_tokens": 500
  }'

준비물

• EvoLink 계정과 API 키. 키는 환경 변수에 저장하고 소스 관리에는 절대 커밋하지 마십시오.
• HTTPS JSON 요청을 보낼 수 있는 클라이언트, 또는 base_url을 바꿀 수 있는 OpenAI 호환 SDK.
• 소규모 대표 평가 세트와 측정 가능한 채택 규칙.
• model ID, 상태, 지연, 토큰 사용량, 재시도, 애플리케이션 수준의 채택 여부를 남기는 로깅.
• 롤아웃 기간에 쓸 fallback 모델, 예를 들어 Gemini 3.7 Flash.

Gemini 3.8 Flash는 텍스트, 이미지, 비디오, 오디오, PDF 입력을 받아 텍스트를 반환합니다. Google 문서 기준으로 input 컨텍스트는 1,048,576 토큰, output은 최대 65,536 토큰입니다. 이 한도는 용량이지, 모든 요청을 가득 채울 이유가 아닙니다.

API 인터페이스 선택

EvoLink는 Gemini 워크로드에 유용한 두 가지 요청 방식을 제공합니다.

OpenAI 호환 Python 예제

OpenAI Python 패키지를 설치한 뒤 EvoLink를 가리키도록 설정합니다.

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["EVOLINK_API_KEY"],
    base_url="https://direct.evolink.ai/v1",
)

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[
        {
            "role": "system",
            "content": "Answer with concise, testable recommendations.",
        },
        {
            "role": "user",
            "content": "Review this deployment plan and identify missing rollback gates.",
        },
    ],
    max_tokens=800,
)

print(response.choices[0].message.content)

첫 요청은 단순하게 유지하십시오. tool, 긴 컨텍스트, 스트리밍을 추가하기 전에 인증, 라우트 접근, 응답 파싱, usage 필드를 먼저 확인하십시오.

Gemini Native 요청 예제

curl "https://direct.evolink.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Create a five-step canary checklist for this API release."}]
    }],
    "generationConfig": {
      "maxOutputTokens": 800,
      "thinkingConfig": {"thinkingLevel": "medium"}
    }
  }'

Thinking Level과 마이그레이션 규칙

오래된 Gemini 클라이언트를 마이그레이션할 때는 다음 항목을 점검하십시오.

HTTP 200이 돌아왔다고 끝이 아닙니다. 마이그레이션 후에는 구조화 출력, tool 인자, 멀티턴 상태, 거부 동작을 다시 검증하십시오.

컨텍스트 낭비 없는 멀티모달 입력

이 모델은 텍스트, 이미지, 비디오, 오디오, PDF를 이해할 수 있지만, 1M 토큰 윈도가 있다고 해서 모든 대용량 페이로드가 유용해지는 것은 아닙니다. 컨텍스트는 의도를 가지고 구성하십시오.

• 판단에 필요한 문서 섹션이나 미디어 구간만 포함하십시오.
• 안정적인 시스템 지시, 리포지토리 지침, tool 스키마는 일관된 접두부에 두어 cache가 도움이 될 여지를 만드십시오.
• 아카이브 전체를 첨부하기 전에 관련 근거를 먼저 검색해 가져오십시오.
• 태스크에 맞는 output 예산을 정하십시오. 65,536 토큰 최대치는 상한일 뿐입니다.
• input 토큰과 cache 읽기 토큰을 분리해 기록해서 "긴 컨텍스트"가 피할 수 있는 지출을 가리지 않게 하십시오.

반복되는 긴 문서라면 안정적인 프롬프트 접두부에서 cache 적중 동작을 비교하십시오. Google의 도입 cache 읽기 요금은 2026년 12월 31일까지 1M 토큰당 $0.075이지만, EvoLink 청구는 실제 계정에서 확인해야 합니다.

5단계 프로덕션 롤아웃

1. 접근 권한과 가격 확인

권한을 제한한 테스트 키를 만들고, 계정의 사용 가능한 라우트에 모델이 보이는지 확인한 뒤, 작은 요청을 보내고 그 결과의 usage 또는 청구 기록을 점검하십시오. 공개 모델 페이지는 제공 의도를 확인해 줄 뿐, 계정별 호출 경로를 보증하지 않습니다.

2. 요청 계약 검증

동기 요청부터 테스트하십시오. 그다음 스트리밍, 구조화 출력, tool, 긴 컨텍스트, 멀티모달 입력을 각각 별도 케이스로 테스트하십시오. 이렇게 하면 프로토콜 실패와 모델 품질 실패를 분리할 수 있습니다.

3. 고정 평가 세트 리플레이

같은 thinking level에서 3.8 Flash를 현재 기준 모델과 비교하십시오. 첫 시도 성공률, 채택된 산출물, output 토큰과 thinking 토큰, cache 적중, 유효한 tool call, 지연, 사람의 수정, fallback 비율을 측정하십시오.

4. 관측 가능한 트래픽으로 Canary

낮은 비율이나 리스크가 낮은 워크로드 유형부터 시작하십시오. 선택한 model ID와 평가 코호트를 모든 trace에 붙이십시오. 집계된 HTTP 성공률만 보고 자동 승격하지 마십시오.

5. 문서화된 게이트로 승격 또는 Rollback

미리 정의한 품질·비용·지연 임계값을 통과했을 때만 승격하십시오. 치명적 오류, 채택 태스크당 비용, 지연이 한계를 넘으면 이전 model 값을 복원해 rollback하십시오.

프로덕션에 필요한 오류 처리

rate limit(요청 한도 초과), 업스트림 불가, 전송 타임아웃 같은 일시적 실패에만 횟수를 제한한 재시도를 사용하십시오. 잘못된 페이로드나 지원되지 않는 파라미터를 그대로 재시도하지 마십시오.

권장 동작:

• 일시적 실패는 지수 백오프와 jitter로 재시도합니다.
• 최대 시도 횟수와 종단 간 데드라인을 설정합니다.
• 애플리케이션이 부수 효과를 만들 수 있는 곳에서는 멱등성 전략을 재사용합니다.
• 요청 ID와 민감 정보를 제거한 오류 본문을 기록합니다. API 키나 민감한 프롬프트는 절대 기록하지 않습니다.
• 데드라인이나 오류 임계값에 도달하면 테스트를 거친 fallback으로 라우팅합니다.
• 반복되는 400번대 오류는 기다려서 해결될 용량 문제가 아니라 고쳐야 할 계약 문제로 취급합니다.

관측성 체크리스트

모든 요청에 대해 다음을 수집하십시오.

• 애플리케이션 기능과 평가 코호트
• 요청한 model ID와 실제 서빙된 model ID
• 프로토콜과 엔드포인트 계열
• thinking level과 output 한도
• 반환되는 경우 input, output, thinking, cache 읽기 토큰
• 지연, 상태, 오류 유형, 재시도 횟수
• tool call 유효성 또는 스키마 검증 결과
• 애플리케이션 채택 여부, 리뷰어 수정, fallback 결과.

이 데이터가 있어야 통합 API 게이트웨이가 불투명한 프록시가 아니라 모델 선택을 뒷받침하는 도구가 됩니다. 하나의 클라이언트 뒤에 여러 Gemini 라우트를 두면서도 어느 라우트가 가치를 만드는지 알 수 있습니다.

흔히 저지르는 설정 실수

• model ID로 gemini-3.8-flash 대신 gemini-3-8-flash를 보내는 것.
• OpenAI 호환 엔드포인트에 Gemini native contents를 보내는 것.
• minimal이 조용히 low로 다운그레이드되는 데 기대는 것, thinkingBudget과 thinkingLevel을 함께 쓰는 것, 무시되는 샘플링 제어값에 의존하는 것, 대화를 role model로 끝내는 것.
• 검색이나 관련성 필터링 없이 컨텍스트 윈도를 가득 채우는 것.
• Google의 공개 요금이 EvoLink 계정의 실시간 요금과 같다고 가정하는 것.
• 응답 형식과 청구를 확인하지 않은 채 HTTP 200 한 번으로 성공을 선언하는 것.
• 측정된 fallback 경로 없이 프로덕션 기본값을 바꾸는 것.

FAQ

Gemini 3.8 Flash의 model ID는 무엇입니까?

어떤 EvoLink 엔드포인트를 써야 합니까?

OpenAI Python SDK를 쓸 수 있습니까?

어떤 thinking level에서 시작해야 합니까?

Gemini 3.8 Flash는 이미지, 비디오, 오디오, PDF를 지원합니까?

입력 모달리티로는 지원합니다. 출력은 텍스트이며, 이미지·오디오 생성이나 실시간 스트림 생성은 제공하지 않습니다.

3.8 Flash가 3.7 Flash보다 쌉니까?

Google 도입 기간의 요금표 기준으로는 아닙니다. input, output, cache 읽기 요금이 같습니다. Google은 3.8이 토큰을 더 많이 쓴다고 밝혔으므로, 채택 태스크당 총비용으로 비교하십시오.

연동이 프로덕션 준비가 됐는지 어떻게 확인합니까?

호출 성공과 그 청구 기록을 확인하고, 사용하는 프로토콜 기능을 각각 테스트하고, 고정 평가 세트를 리플레이하고, 실제 트래픽으로 canary를 돌리고, 명시적인 rollback을 유지하십시오.

모든 Gemini 라우트를 어디서 비교할 수 있습니까?

출처 및 검증 노트

• Google: Gemini 3.8 Flash 출시 발표
• Google AI for Developers: Gemini 3.8 Flash 모델
• Google AI for Developers: Gemini API 가격
• Google Cloud: Gemini 3.8 Flash 가이드
• EvoLink: Gemini native API 퀵스타트
• EvoLink: Gemini native API 레퍼런스
• EvoLink: Gemini OpenAI 호환 퀵스타트