비관리형 Vertex AI 배치

비관리형 Vertex AI 배치 (Unmanaged Vertex AI Batches)

Vertex AI 배치 작업을 위한 두 가지 경로 중 하나를 다루는 엔터프라이즈 기능이에요. 관리형 경로는 파일 업로드와 형식 변환을 자동으로 처리하지만, 비관리형 경로는 배치 파일을 Vertex AI 네이티브 형식으로 GCS에 직접 업로드할 수 있게 해주며, LiteLLM은 변환을 건너뛰되 활성화하면 비용을 추적해요.

출처: 문서

본문

엔터프라이즈 기능 이 기능은 LiteLLM Enterprise 라이선스가 필요해요. 무료 30일 체험판을 시작하거나 데모를 예약하세요. Enterprise에 포함된 내용을 확인하세요.

LiteLLM은 Vertex AI 배치 작업을 위한 두 가지 경로를 지원해요. 관리형 경로는 파일 업로드와 형식 변환을 자동으로 처리해요. 비관리형 경로는 배치 파일을 Vertex AI 네이티브 형식으로 GCS에 직접 업로드할 수 있게 해주며, LiteLLM은 변환을 건너뛰되 활성화하면 비용을 추적해요.

동작 방식

설정

프록시 config에서 비용 추적을 활성화해요:

general_settings:
  track_unmanaged_batch_cost: true  # Default: false

배치하려는 모델에 대해 vertex_ai 배포를 구성해요. 폴러는 이 배포의 자격 증명을 사용해 Vertex를 폴링하고 비용을 계산해요:

model_list:
  - model_name: gemini-3.8-flash
    litellm_params:
      model: vertex_ai/gemini-3.8-flash
      vertex_project: my-gcp-project
      vertex_location: us-central1
      vertex_credentials: /path/to/service-account.json

GCS 경로 요구 사항

LiteLLM이 자격 증명 조회용 모델 이름을 알아낼 수 있도록 GCS 경로에 publishers/google/models/<model-name>/이 포함되어야 해요.

gs://my-bucket/<any-prefix>/publishers/google/models/gemini-3.8-flash/<filename>.jsonl

버킷 이름과 publishers/ 앞의 접두어는 무엇이든 될 수 있어요.

배치 파일 형식

비관리형 배치는 Vertex AI 네이티브 JSONL 형식이어야 해요. 관리형 경로는 OpenAI 형식을 받아 변환하지만, 비관리형 경로는 변환을 완전히 건너뛰므로 Vertex AI 형식을 직접 제공해야 해요:

{"custom_id": "1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": "What is 2+2?"}]}}
{"custom_id": "2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": "What is 3+3?"}]}}

사용법

1. GCS에 업로드

gsutil cp batch.jsonl gs://my-bucket/batches/publishers/google/models/gemini-3.8-flash/batch.jsonl

2. 배치 만들기

GCS URI를 input_file_id로 전달해요:

curl -X POST http://localhost:4000/v1/batches \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "gs://my-bucket/batches/publishers/google/models/gemini-3.8-flash/batch.jsonl",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "custom_llm_provider": "vertex_ai"
  }'

응답에는 원시 Vertex 숫자 작업 ID (예: 8823717160934178816)가 포함돼요.

3. 상태 모니터링

프록시가 OpenAI 대신 Vertex로 라우팅하도록 custom_llm_provider=vertex_ai를 전달해요:

curl -X GET "http://localhost:4000/v1/batches/8823717160934178816?custom_llm_provider=vertex_ai" \
  -H "Authorization: Bearer ***"

4. 결과 가져오기

status가 completed이면 출력 파일 위치가 output_file_id에 있어요. GCS에서 다운로드해요:

gsutil cp gs://my-bucket/output/batch-results.jsonl .

각 줄은 Vertex AI 응답 객체예요:

{"custom_id": "1", "response": {"status_code": 200, "body": {"choices": [{"message": {"content": "2 + 2 = 4"}}]}}}

비용 추적

track_unmanaged_batch_cost: true를 설정하면 CheckBatchCost 폴러가 비용 추적을 자동으로 처리해요. 폴러는 GCS 경로에서 모델을 추출하고, 구성된 vertex_ai 배포를 사용해 결과를 위해 Vertex를 폴링하며, 토큰 비용을 계산하고 배치를 처리된 것으로 표시해요. 비용은 http://localhost:4000/ui/?page=logs의 프록시 로그 UI에 나타나요.

폴링 간격은 general_settings의 proxy_batch_polling_interval로 제어돼요 (기본 초 단위; 폴러는 0-30초 지터를 추가해요). 테스트 중 더 빠른 피드백을 원하면 10으로 설정하세요.

폴러가 쓰는 지출 로그 행은 관리형 배치가 얻는 것과 같은 모양이에요. 각 필드의 의미와 부분 실패 배치를 읽는 방법은 Observability를 참고하세요.

문제 해결

배치 비용이 계산되지 않음. track_unmanaged_batch_cost: true가 설정되어 있는지, GCS 경로에 publishers/google/models/<model>/이 포함되어 있는지, vertex_ai 배포가 구성되어 있는지 확인하세요. 다음과 같은 로그 라인을 찾아보세요:

Skipping unmanaged vertex batch 8823717160934178816: no vertex_ai deployment configured for model gemini-3.8-flash

비용이 0임. Vertex AI는 배치가 완전히 완료된 후에만 응답 본문에 토큰 사용량을 포함해요. status가 completed인데 비용이 0이면, 출력 파일을 수동으로 다운로드해 usage 필드가 있는 응답 데이터가 포함되어 있는지 확인하세요.

관리형 vs 비관리형

같이 보기

• Managed Batches
• Vertex AI Batch Prediction

더 알아보기 (Learn more)

• Managed Batches
• Vertex AI Batch Prediction