Bedrock Batches

Bedrock Batches

LiteLLM을 통해 Amazon Bedrock Batch Inference API를 사용해요.

출처: 문서

본문

개요 (Overview)

속성	설명
설명	Amazon Bedrock Batch Inference는 대규모 데이터셋에 대해 비동기적으로 추론을 실행할 수 있게 해요
공급자 문서	AWS Bedrock Batch Inference
비용 추적	✅ 지원

용도:

• Bedrock 모델로 대규모 데이터셋에 배치 추론 실행
• 채팅 완성 모델과 동일하게 키/사용자/팀별 배치 모델 접근 제어
• 배치 입력/출력 파일용 S3 스토리지 관리

(Proxy Admin) 사용법

개발자에게 Bedrock Batch 모델 접근을 주는 방법이에요.

1. config.yaml 설정

각 모델에 mode: batch를 지정해 개발자에게 배치 모델임을 알리고, S3 버킷과 AWS 자격 증명을 구성해요.

model_list:
  - model_name: "bedrock-batch-claude"
    litellm_params:
      model: bedrock/us.anthropic.claude-sonnet-5
      #########################################################
      ########## batch specific params ########################
      s3_bucket_name: litellm-proxy
      s3_region_name: us-west-2
      s3_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      s3_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_batch_role_arn: arn:aws:iam::888602223428:role/service-role/AmazonBedrockExecutionRoleForAgents_BB9HNW6V4CV
      # Optional: Custom KMS encryption key for the S3 input upload and the batch output
      # s3_encryption_key_id: arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012
      # Optional: AWS account id that owns the S3 buckets, when they live in another account
      # s3_bucket_owner: "123456789012"
      model_info:
        mode: batch  # 👈 SPECIFY MODE AS BATCH, to tell user this is a batch model

필수 파라미터:

파라미터	설명
s3_bucket_name	배치 입력/출력 파일용 S3 버킷
s3_region_name	S3 버킷용 AWS 지역
s3_access_key_id	S3 버킷용 AWS 접근 키
s3_secret_access_key	S3 버킷용 AWS 시크릿 키
aws_batch_role_arn	Bedrock 배치 작업용 IAM 역할 ARN. Bedrock Batch API는 IAM 역할 ARN이 설정되어야 해요
mode: batch	LiteLLM에 이것이 배치 모델임을 표시

선택 파라미터:

파라미터	설명
s3_encryption_key_id	LiteLLM이 S3에 업로드하는 배치 입력 파일과 배치 출력 데이터용 사용자 지정 KMS 암호화 키 ID. LiteLLM이 업로드를 서명하는 자격 증명에 해당 키에 대한 kms:GenerateDataKey가 필요. 지정하지 않으면 Bedrock은 AWS 관리 암호화 키를 사용
s3_bucket_owner	배치 입력/출력 S3 버킷을 소유한 AWS 계정 id. Bedrock 작업의 입력·출력 데이터 구성 모두에 s3BucketOwner로 전송. 버킷이 배치 작업을 실행하는 계정과 다른 계정에 있으면 설정. AWS_S3_BUCKET_OWNER 환경 변수로도 설정 가능

2. 가상 키 생성

curl -L -X POST 'https://{PROXY_BASE_URL}/key/generate' \
  -H 'Authorization: Bearer ***' \
  -H 'Content-Type: application/json' \
  -d '{"models": ["bedrock-batch-claude"]}'

이제 가상 키로 배치 모델에 접근할 수 있어요 (개발자 흐름 참고).

(개발자) 사용법

LiteLLM 관리 파일을 만들고 파일로 Bedrock Batch CRUD 작업을 실행하는 방법이에요.

1. request.jsonl 생성

/model_group/info로 사용 가능한 모델 확인 (mode: batch인 모델 모두). .jsonl의 model을 /model_group/info의 모델로 설정해요. LiteLLM이 이를 bedrock 배포별 값(예: bedrock/us.anthropic.claude-sonnet-5)으로 변환해요.

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "bedrock-batch-claude", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello world!"}], "max_tokens": 1000}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "bedrock-batch-claude", "messages": [{"role": "system", "content": "You are an unhelpful assistant."}, {"role": "user", "content": "Hello world!"}], "max_tokens": 1000}}

2. 파일 업로드

LiteLLM 관리 파일과 요청 검증을 활성화하려면 target_model_names: "<model-name>"을 지정해요. model-name은 request.jsonl의 model-name과 같아야 해요. 파일은 config에 지정된 S3 버킷에 기록되고 Bedrock 배치 추론용으로 준비돼요.

Python:

from openai import OpenAI

client = OpenAI(
    base_url="http://0.0.0.0:4000",
    api_key="sk-<your-litellm-api-key>",
)

# Upload file
batch_input_file = client.files.create(
    file=open("./bedrock_batch_completions.jsonl", "rb"),
    # {"model": "bedrock-batch-claude"} <-> {"model": "bedrock/us.anthropic.claude-sonnet-5"}
    purpose="batch",
    extra_body={"target_model_names": "bedrock-batch-claude"}
)
print(batch_input_file)

curl:

curl http://localhost:4000/v1/files \
  -H "Authorization: Bearer ***" \
  -F purpose="batch" \
  -F file="@bedrock_batch_completions.jsonl" \
  -F extra_body='{"target_model_names": "bedrock-batch-claude"}'

3. 배치 생성

Python:

# Create batch
batch = client.batches.create(
    input_file_id=batch_input_file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={"description": "Test batch job"},
)
print(batch)

curl:

curl http://localhost:4000/v1/batches \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata": {"description": "Test batch job"}
  }'

4. 배치 결과 조회

배치 작업이 완료되면 S3에서 결과를 다운로드해요.

Python:

# Wait for batch completion (check status periodically)
batch_status = client.batches.retrieve(batch_id=batch.id)

if batch_status.status == "completed":
    # Download the output file
    result = client.files.content(
        file_id=batch_status.output_file_id,
        extra_headers={"custom-llm-provider": "bedrock"}
    )

    # Save or process the results
    with open("batch_output.jsonl", "wb") as f:
        f.write(result.content)

    # Parse JSONL results
    for line in result.text.strip().split('\n'):
        record = json.loads(line)
        print(f"Record ID: {record['recordId']}")
        print(f"Output: {record.get('modelOutput', {})}")

curl:

# First retrieve batch to get output_file_id
curl http://localhost:4000/v1/batches/batch_abc123 \
  -H "Authorization: Bearer ***"

# Then download the output file
curl http://localhost:4000/v1/files/{output_file_id}/content \
  -H "Authorization: Bearer ***" \
  -H "custom-llm-provider: bedrock" \
  -o batch_output.jsonl

LiteLLM 직접 사용:

import litellm
from litellm import file_content

# Download using litellm directly (bypasses proxy managed files)
result = file_content(
    file_id=batch_status.output_file_id,  # Can be S3 URI or unified file ID
    custom_llm_provider="bedrock",
    aws_region_name="us-west-2",
)

# Process results
print(result.text)

출력 형식:

배치 출력 파일은 JSONL 형식이며 각 줄에 다음이 포함돼요:

{
  "recordId": "request-1",
  "modelInput": {
    "messages": [...],
    "max_tokens": 1000
  },
  "modelOutput": {
    "content": [...],
    "id": "msg_abc123",
    "model": "us.anthropic.claude-sonnet-5",
    "role": "assistant",
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 15,
      "output_tokens": 10
    }
  }
}

FAQ

내 파일은 어디에 기록되나요?

target_model_names이 지정되면 파일은 Bedrock 배치 모델 구성에 설정된 S3 버킷에 기록돼요.

어떤 모델이 지원되나요?

AWS가 배치 추론에 나열하는 Bedrock 모델이라면, LiteLLM이 입력 파일의 OpenAI 형식 레코드를 그 모델의 요청 본문으로 변환할 수 있는 한 동작해요. 오늘은 Anthropic Claude 모델, Amazon Nova 모델(각 레코드가 Nova가 기대하는 Converse 요청 형태로 작성됨), /v1/embeddings 레코드용 Amazon Titan Text Embeddings V2, 그리고 openai.gpt-oss-120b-1:0, Qwen, DeepSeek 같은 OpenAI 호환 Bedrock 모델(레코드가 OpenAI 스타일의 chat 본문으로 그대로 전달됨)을 지원해요. Chat 레코드는 url로 /v1/chat/completions, /v1/completions, /v1/responses를 쓸 수 있고, completions/responses 레코드는 업로드 전에 chat 요청으로 변환돼요. Titan Text Embeddings V2가 오늘 유일하게 변환되는 임베딩 모델이에요.

지역에서 AWS가 배치 작업에 허용하는 모델 id를 사용하세요. 대부분의 최신 모델은 cross-region inference profile로만 배치 작업을 실행하므로 id에 보통 us.(또는 eu., apac.) 접두사가 붙어요 (예: amazon.nova-lite-v1:0 대신 us.amazon.nova-lite-v1:0). 또한 Bedrock은 모델과 무관하게 100개 미만 레코드의 작업은 거부해요.

비-Anthropic 배치 모델도 위 Claude 예시와 같은 방식으로 구성돼요:

model_list:
  - model_name: "bedrock-batch-nova"
    litellm_params:
      model: bedrock/us.amazon.nova-lite-v1:0
      s3_bucket_name: litellm-proxy
      s3_region_name: us-east-1
      s3_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      s3_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_batch_role_arn: arn:aws:iam::123456789012:role/LiteLLMBedrockBatchRole
      model_info:
        mode: batch
  - model_name: "bedrock-batch-titan-embeddings"
    litellm_params:
      model: bedrock/amazon.titan-embed-text-v2:0
      s3_bucket_name: litellm-proxy
      s3_region_name: us-east-1
      s3_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      s3_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_batch_role_arn: arn:aws:iam::123456789012:role/LiteLLMBedrockBatchRole
      model_info:
        mode: batch

입력 파일의 레코드는 그 model_name을 참조하고({"model": "bedrock-batch-nova", ...}), 업로드는 target_model_names를 같은 이름으로 설정하며, 배치는 chat 모델이면 endpoint를 /v1/chat/completions로, 임베딩 모델이면 /v1/embeddings로 설정해 생성해요. aws_batch_role_arn의 IAM 역할에는 배치 작업을 실행하는 모든 모델에 대한 bedrock:InvokeModel이 필요해요.

LiteLLM이 아직 변환하지 못하는 Bedrock 모델(예: 다른 임베딩 모델)이 필요하면 여기에 이슈를 등록해 주세요.

사용자 지정 KMS 암호화 키는 어떻게 쓰나요?

S3 버킷이 사용자 지정 KMS 암호화 키를 요구하면 s3_encryption_key_id로 구성에 지정할 수 있어요. 항목 키는 LiteLLM이 건드리는 두 객체를 모두 커버해요: 버킷에 업로드하는 배치 입력 파일과 Bedrock이 다시 쓰는 배치 출력. 입력 업로드는 x-amz-server-side-encryption: aws:kms와 이 키 ARN으로 서명되므로, LiteLLM이 업로드에 사용하는 AWS 신원은 키에 대한 kms:GenerateDataKey가 필요해요. 키를 설정하기 전에 이를 부여하세요. 그렇지 않으면 POST /v1/files가 S3 AccessDenied로 실패해요.

암호화 키는 두 가지 방법으로 설정할 수 있어요:

config.yaml (권장):

model_list:
  - model_name: "bedrock-batch-claude"
    litellm_params:
      model: bedrock/us.anthropic.claude-sonnet-5
      s3_encryption_key_id: arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012
      # ... other params

환경 변수:

export AWS_S3_ENCRYPTION_KEY_ID=arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012

다른 AWS 계정이 소유한 S3 버킷은 어떻게 쓰나요?

Bedrock은 입력·출력 버킷이 s3BucketOwner에 지정된 계정에 속하는지 확인하며, 이 필드가 없으면 기본적으로 배치 작업을 실행하는 계정을 사용해요. 버킷이 다른 계정에 있으면 버킷 정책이 접근을 허용하더라도 작업이 S3 권한 에러로 검증 실패해요. 버킷을 소유한 계정의 id로 s3_bucket_owner를 설정하면 LiteLLM이 입력·출력 데이터 구성 모두에 전송해요.

Proxy에서는 /v1/batches 요청 본문에 전달된 s3_bucket_owner가 배포의 litellm_params 값보다 우선하고, 그 값이 AWS_S3_BUCKET_OWNER 환경 변수보다 우선해요. 이는 router가 s3_bucket_name이나 s3_encryption_key_id 같은 다른 모든 배포 파라미터에 적용하는 순서와 같아요. 아무것도 설정하지 않으면 필드가 생략되고 Bedrock이 기본값을 유지해요.

더 알아보기 (Learn more)

• LiteLLM 개요
• LiteLLM Python SDK 사용법
• LiteLLM Proxy Server 설정
• 지원되는 공급업체 전체 목록