클라우드 API 프로바이더 (Gemini, Bedrock, Azure)

이 페이지에서는 API 키 하나만으로는 설정할 수 없는 세 가지 하이퍼스케일러 모델 백엔드를 다룹니다. Google Gemini(직접 API, Gemini CLI OAuth, Vertex AI), AWS Bedrock(SigV4 또는 Bearer 인증, 교차 리전 추론 프로파일), Azure OpenAI(리소스/배포 범위 엔드포인트)입니다. 또한 default_provider와 api_url을 따로 수정하지 않고도 커스텀 또는 Codex 스타일 엔드포인트를 지정할 수 있는 [model_providers] 네임드 프로파일 구성 방식도 설명합니다.

모델이 GCP, AWS, 또는 Azure 뒤에 위치한 경우 이 페이지를 참고하세요. 키 하나로 바로 사용할 수 있는 간단한 프로바이더는 프로바이더 빠른 시작을 먼저 확인하고, 전체 백엔드 목록은 프로바이더 카탈로그를 참고하세요.

참고

세 프로바이더 모두 Revka의 통일된 우선순위로 자격 증명을 확인합니다. 명시적 설정값 → 프로바이더별 환경 변수 → REVKA_API_KEY / API_KEY 폴백 순입니다. 클라우드 자격 증명은 아래의 프로바이더별 환경 변수를 사용하는 것을 권장합니다.

Google Gemini

gemini 프로바이더는 다양한 인증 방식을 지원하는 완전한 Google 통합입니다. default_provider = "gemini" 또는 -p gemini CLI 플래그로 선택합니다.

default_provider = "gemini"
default_model    = "gemini-2.5-pro"

revka agent -p gemini --model gemini-2.5-pro -m "Hello"

추론 모델의 thinking 과정은 최종 응답에서 필터링되므로, Gemini 추론 모델에서 깔끔한 텍스트 결과를 받을 수 있습니다.

인증 전략

프로바이더는 다음 순서로 자격 증명을 확인하며, 처음으로 성공한 방식을 사용합니다.

1. Vertex AI ADC (GOOGLE_GENAI_USE_VERTEXAI가 true/1이고 GOOGLE_CLOUD_PROJECT가 설정된 경우 활성화) — 명시적 API 키보다 먼저 확인합니다.
2. config.toml에 명시된 API 키 (api_key).
3. GEMINI_API_KEY 환경 변수.
4. GOOGLE_API_KEY 환경 변수.
5. revka auth login --provider gemini로 저장된 관리형 OAuth 프로파일.
6. ~/.gemini/oauth_creds.json에서 자동으로 검색되는 Gemini CLI OAuth 토큰.

필드	위치	설명
GEMINI_API_KEY	환경 변수	직접 API 키. ?key= 쿼리 파라미터로 전달됩니다.
GOOGLE_API_KEY	환경 변수	직접 API 키의 대체 이름.
GOOGLE_CLOUD_PROJECT	환경 변수	OAuth/Vertex 요청에 사용되는 GCP 프로젝트 ID (GOOGLE_CLOUD_PROJECT_ID로 폴백).
GOOGLE_APPLICATION_CREDENTIALS	환경 변수	Application Default Credentials(ADC)용 서비스 계정 JSON 경로.

두 가지 API 엔드포인트

Gemini는 인증 방식에 따라 두 가지 다른 엔드포인트를 사용합니다.

• API 키 사용자는 공개 엔드포인트 https://generativelanguage.googleapis.com/v1beta에 ?key=… 형태로 키를 전달합니다.
• OAuth 사용자(Gemini CLI 또는 관리형 프로파일)는 Google 내부 Code Assist 엔드포인트 https://cloudcode-pa.googleapis.com/v1internal에 Authorization: Bearer … 형태로 토큰을 전달합니다.

OAuth 토큰은 프로세스 내에서 자동으로 갱신되므로, 장시간 실행되는 게이트웨이도 수동 재인증 없이 계속 작동합니다.

Vertex AI 및 ADC

공개 API 대신 Vertex AI를 통해 Gemini를 실행하려면, Vertex 환경을 구성하고 default_provider = "gemini"를 유지합니다.

export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_PROJECT="my-gcp-project"
export GOOGLE_CLOUD_LOCATION="us-central1"   # default region

Vertex AI는 호스트에서 Google 자격 증명을 사용할 수 있어야 합니다.

• Cloud Run, GCE, 또는 GKE에서는 서비스 계정에 Vertex 접근 권한이 있으면 GCP 메타데이터 서버가 자격 증명을 자동으로 제공합니다(키 불필요).
• GCP 외부 환경에서는 ADC가 자격 증명을 확인할 수 있도록 GOOGLE_APPLICATION_CREDENTIALS를 서비스 계정 JSON으로 설정해야 합니다. 이 설정 없이는 GCP 외부 호스트에서 Vertex AI에 접근할 수 없습니다.

팁

API 키를 노출하지 않고 기존 Gemini CLI 구독을 재사용하려면, gemini 바이너리를 직접 실행하는 서브프로세스 기반의 gemini-cli 프로바이더를 사용하세요. OAuth 및 구독 프로바이더를 참고하세요.

AWS Bedrock

bedrock 프로바이더는 AWS Bedrock Converse API를 사용합니다. 네이티브 툴 호출과 프롬프트 캐싱(cachePoint)을 지원하며, AWS SDK 의존성 없이 요청에 직접 서명합니다. default_provider = "bedrock" 또는 -p bedrock으로 선택합니다.

default_provider = "bedrock"
default_model    = "anthropic.claude-sonnet-4-5-20250929-v1:0"

각 요청은 리전별 Bedrock Runtime 엔드포인트로 HTTPS POST됩니다.

POST https://bedrock-runtime.{region}.amazonaws.com/model/{model_id}/converse

기본 리전은 us-east-1입니다. 기본 출력은 4096 토큰으로 제한되며, 설정에서 provider_max_tokens로 변경할 수 있습니다.

주의

Bedrock 모델 ID는 Anthropic 공개 API ID와 다릅니다. Bedrock의 anthropic.claude-* 형식(예: anthropic.claude-sonnet-4-5-20250929-v1:0)을 사용해야 하며, Anthropic ID를 그대로 사용하지 마세요.

SigV4 vs Bearer

Bedrock은 두 가지 인증 모드를 지원하며, Bearer 토큰이 있으면 항상 우선 적용됩니다.

모드	조건	자격 증명
Bearer 토큰	BEDROCK_API_KEY가 설정된 경우	토큰이 Authorization: Bearer …로 전달됩니다. 설정 시 권장되는 가장 간단한 방식입니다.
SigV4 서명	BEDROCK_API_KEY가 없는 경우	bedrock 서명 서비스에 대해 표준 AWS 액세스 키/시크릿 키로 서명합니다.

SigV4의 경우 환경 변수에서 자격 증명을 먼저 확인하고, 없으면 EC2 인스턴스 메타데이터를 확인합니다.

변수	설명
AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY	SigV4용 장기 액세스 키.
AWS_SESSION_TOKEN	임시/STS 세션 토큰(역할 가정(assumed-role) 자격 증명 사용 시).
AWS_REGION 또는 AWS_DEFAULT_REGION	서명/엔드포인트 리전. 기본값: us-east-1.
BEDROCK_API_KEY	선택적 Bearer 토큰. 설정 시 SigV4를 대체합니다.

IAM 역할이 연결된 EC2, ECS, 또는 Lambda에서는 EC2 IMDSv2(인스턴스 메타데이터 서비스)를 통해 임시 자격 증명을 자동으로 검색하므로, 환경 변수에 키를 설정하지 않아도 됩니다.

교차 리전 추론 프로파일

처리량을 높이기 위해 여러 리전에 부하를 분산하는 Bedrock 교차 리전 추론 프로파일을 지원합니다. 사용하려면 모델 ID에 리전 그룹 접두사를 포함하세요. 예를 들어, 미국 추론 프로파일에는 us. 접두사를 사용합니다.

default_provider = "bedrock"
default_model    = "us.anthropic.claude-sonnet-4-5-20250929-v1:0"

접두사는 별도 설정이 아니라 모델 ID의 일부입니다. 접두사를 생략하면 추론 프로파일 대신 리전 모델에 직접 요청합니다.

Azure OpenAI

azure-openai 프로바이더는 모델 이름이 아닌 리소스와 배포 단위로 범위가 지정된 Azure OpenAI Service Chat Completions 엔드포인트를 호출합니다. 네이티브 툴 호출과 추론 콘텐츠 처리를 지원합니다. default_provider = "azure-openai" 또는 -p azure로 선택합니다. 허용 별칭: azure, azure-openai, azure_openai.

default_provider = "azure-openai"
default_model    = "gpt-4o"

엔드포인트와 자격 증명은 환경 변수로 설정합니다.

export AZURE_OPENAI_API_KEY="<your-key>"
export AZURE_OPENAI_RESOURCE="my-resource"
export AZURE_OPENAI_DEPLOYMENT="gpt-4o"
export AZURE_OPENAI_API_VERSION="2024-08-01-preview"   # optional

변수	기본값	설명
AZURE_OPENAI_API_KEY	—	API 키. Bearer 토큰이 아닌 api-key 요청 헤더로 전달됩니다.
AZURE_OPENAI_RESOURCE	my-resource	Azure 리소스 이름 — 엔드포인트 호스트명의 <resource> 부분.
AZURE_OPENAI_DEPLOYMENT	gpt-4o	배포 이름. 실제로 요청을 처리하는 모델은 default_model이 아닌 이 값으로 결정됩니다.
AZURE_OPENAI_API_VERSION	2024-08-01-preview	API 버전. Microsoft가 새 GA 버전을 출시하면 업데이트하세요.

Revka는 위 값들로 요청 URL을 구성합니다.

POST https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version={version}
api-key: {AZURE_OPENAI_API_KEY}

참고

Azure에서는 배포 이름이 모델 선택자 역할을 합니다. 요청 본문에 model 필드가 포함되지 않습니다. config.toml의 default_model은 참고용이며, 실제로 사용할 배포는 AZURE_OPENAI_DEPLOYMENT로 설정하세요.

[model_providers] 네임드 프로파일

[model_providers]를 사용하면 config.toml에 네임드 프로바이더 프로파일을 정의할 수 있습니다. Codex 앱 서버 호환 레이아웃이며, default_provider에 이름을 지정하는 것만으로 해당 프로파일을 활성화할 수 있습니다. 활성 프로바이더가 프로파일 키와 일치하면 Revka는 최상위 설정 위에 해당 프로파일 설정을 적용합니다(명시적으로 설정한 최상위 값이 항상 우선합니다).

default_provider = "my-endpoint"

[model_providers.my-endpoint]
base_url    = "https://your-api.example.com/v1"
api_path    = "/chat/completions"   # optional path override
max_tokens  = 8192                  # optional output cap
wire_api    = "chat_completions"    # or "responses"

필드	타입	설명
name	string	전환할 프로바이더 타입/이름 (예: openai, 커스텀 프로파일 ID). base_url이 설정된 경우 선택 사항.
base_url	URL (http/https)	OpenAI 호환 베이스 URL. name이 설정된 경우 선택 사항.
api_path	string	기본 /v1/chat/completions 대신 사용할 커스텀 요청 경로 접미사.
wire_api	string	프로토콜 변형: chat_completions 또는 responses.
requires_openai_auth	bool	true이면 키가 없을 때 OpenAI 인증 정보(OPENAI_API_KEY 또는 ~/.codex/auth.json)를 로드합니다.
azure_openai_resource	string	Azure 스타일 프로파일용 Azure 리소스 이름.
azure_openai_deployment	string	Azure 배포 이름.
azure_openai_api_version	string	Azure API 버전 (기본값: 2024-08-01-preview).
max_tokens	integer	최대 출력 토큰 수. 플랫폼 기본값이 모델의 실제 한계를 초과할 때 유용합니다.

각 프로파일은 name 또는 base_url 중 하나 이상을 반드시 정의해야 하며, base_url은 유효한 http/https URL이어야 합니다. 그렇지 않으면 로드 시 설정 유효성 검사가 실패합니다. 활성화 방식은 다음과 같습니다.

• wire_api = "responses"이면 OpenAI Codex Responses API 경로로 요청을 라우팅합니다.
• 그렇지 않고 name이 프로파일 키와 다르면 Revka가 default_provider를 name으로 전환합니다.
• 그렇지 않으면 base_url만으로 해당 프로파일을 custom:<base_url> 엔드포인트로 활성화합니다.

default_provider 한 줄만 변경해 여러 엔드포인트 정의를 나란히 관리하고 전환하는 가장 깔끔한 방법입니다. 순수 custom: / anthropic-custom: 엔드포인트와 extra_headers에 대해서는 로컬, 셀프 호스팅 및 커스텀 엔드포인트를 참고하세요.

관련 페이지

• 프로바이더 빠른 시작 — 프로바이더를 선택하고 키를 설정한 뒤 첫 번째 채팅을 실행합니다.
• 프로바이더 카탈로그 — 베이스 URL, 환경 변수, 기능이 포함된 전체 백엔드 목록.
• OAuth 및 구독 프로바이더 — Gemini CLI, Codex, Claude Code 등 토큰 기반 로그인.
• 라우팅, 안정성 및 튜닝 — 폴백, hint: 라우팅, 타임아웃, provider_max_tokens.
• revka 모델, 프로바이더 및 인증 — 모델 카탈로그 갱신 및 OAuth 프로파일 관리.
• 설정: 프로바이더, 에이전트 및 라우팅 — 이 프로바이더들을 구성하는 config.toml 키 설명.