업스트림 장애가 당신의 장애가 되지 않게 하세요.AIHubMix는 콘솔에서 한 번만 설정하면 적용되며 클라이언트 코드를 수정할 필요가 없는 Key 단위의 두 가지 기능을 제공합니다:
- 모델명 매핑(Model Mapping)은 게이트웨이 계층에서 클라이언트 요청의 모델 별칭을 실제 업스트림 모델로 변환하는 기능입니다.
- 오류 시 폴백 모델(Fallback)은 주 모델 호출이 실패했을 때 게이트웨이가 미리 설정한 우선순위 순서대로 자동으로 백업 모델을 시도하는, 클라이언트가 인지하지 못하는 기능입니다.
AIHubMix는 Key 단위로 모델명 매핑과 오류 시 폴백을 설정할 수 있으며, 최종 응답 모델 기준으로 과금합니다. 두 기능 모두 AIHubMix Key 관리 페이지에서 개별 API Key에 대해 설정합니다.
Model name mapping 과 Fallback models on error 두 섹션에서 각각 설정합니다.
1. 모델명 매핑 (Model Mapping)
모델명 매핑은 「클라이언트가 보는 모델명」과 「AIHubMix가 실제로 호출하는 모델」이 일치하지 않는 문제를 처리하기 위한 것입니다. 이는 Key 단위(per-key)의 별칭 변환으로, 요청의 별칭을 Key에 설정한 대상 모델로 변환합니다.대상 모델은 채널이 선택된 후 플랫폼 내부에서 다시 한 번 채널 단위로 실제 업스트림 모델로 매핑됩니다. 이 계층은 사용자에게 투명하며 설정할 필요가 없습니다. 당신은 「별칭 → 대상 모델」 계층만 신경 쓰면 됩니다.예시:
| 클라이언트 요청 모델명(별칭) | AIHubMix 대상 모델 |
|---|---|
my-gpt | gpt-5.5-pro |
my-fast | gemini-3.1-pro-preview |
my-coder | deepseek-v4 |
my-glm | coding-glm-4.6-free |
위 표의 모델명은 모두 AIHubMix 모델 페이지에서 조회할 수 있습니다.일반적인 용도:
- 클라이언트가 모델명 형식을 제한하는 경우. 예를 들어 Claude Desktop은 모델명이 Claude 스타일을 따르도록 요구합니다(5절 참조).
- 복잡한 모델 ID에 더 짧고 안정적인 별칭을 설정합니다.
- 클라이언트 설정은 그대로 두고 AIHubMix 백엔드에서 실제 모델을 전환합니다.
- 여러 플랫폼이 하나의 연동 명명 규칙을 공유하되 Key에 따라 서로 다른 모델로 라우팅합니다.
문자 단위 일치: 클라이언트가 보내는 모델명은 매핑 좌측과 문자 단위로 일치해야 합니다. 예를 들어my-gpt-5.5와my-gpt-5-5는 서로 다른 문자열이므로, 일치하지 않으면 매핑에 적중하지 않습니다.
2. 오류 시 폴백 모델 (Fallback)
오류 시 폴백 모델은 주 모델이 실패했을 때 순서대로 백업 모델을 시도하기 위한 것입니다. 이는 클라이언트 측 재시도가 아니라, 동일한 Key 설정 하에서 AIHubMix 게이트웨이 측이 수행하는 모델 전환입니다. 연동하는 측에서는 매 요청마다 추가 라우팅 파라미터를 전달할 필요가 없습니다. Fallback은 「하나의 순서가 있는 목록으로 매핑하는 것」으로 이해할 수 있습니다. 주 모델이 실패하면 게이트웨이가 자동으로 목록의 다음 백업 모델로 넘어갑니다. 예시(동일한 Key에 설정):| 순서 | 백업 모델 |
|---|---|
| 1 | gpt-5.4 |
| 2 | gemini-3.1-pro-preview |
2.1 트리거 조건 (모두 충족해야 폴백)
다음 조건이 모두 성립할 때만 폴백이 발생합니다:- Key에 비어 있지 않은 백업 모델 목록이 설정되어 있습니다.
- 주 모델의 모든 채널을 시도했고, 모두 「재시도 가능한 오류」로 실패했습니다(채널 소진).
- 응답이 아직 반환되기 시작하지 않았습니다(첫 바이트 / header가 아직 클라이언트로 전송되지 않음).
- 오류가 Key / 사용자 단위 오류가 아닙니다(아래 2.2 대조표 참조).
2.2 폴백되는 경우와 되지 않는 경우
| 상황 | 폴백 여부 |
|---|---|
| 주 모델 전 채널 「재시도 가능 실패」, 응답 미시작 | ✅ 폴백 |
특정 채널을 지정한 경우(Key 접미사 sk-xxx-{id}, /v1/proxy/{id}/*) | ❌ |
| 응답이 이미 반환되기 시작(스트리밍에서 첫 바이트가 나감) | ❌ |
| 클라이언트 연결 끊김 / 요청 타임아웃 | ❌ |
| 당신의 AIHubMix Key 잔액 부족 / 무효 / 만료 / 비활성화 | ❌ |
| 계정 차단 / 리스크 관리 키워드 적중 | ❌ |
| 무료 주 모델이 할당량 / 빈도 제한에 걸림 | ✅ 백업 유료 모델로 폴백 |
| 백업 목록의 무료 모델 | ⏭️ 해당 항목 건너뛰고 다음으로 계속 |
| 백업 목록 중 Key의 사용 가능 범위를 벗어난 모델 | ⏭️ 건너뜀 |
참고: 여기서 「Key 무효」는 당신 자신의 AIHubMix Key이 무효가 된 것을 의미하며, 이 경우 폴백되지 않습니다. 어떤 업스트림 채널의 key가 망가진 경우라면 게이트웨이가 채널을 교체하며, 채널이 소진된 후에는 여전히 폴백이 가능합니다. 둘을 혼동하지 마세요.
2.3 과금 기준
최종 응답 모델 기준으로 과금합니다. 최종적으로 폴백 모델이 응답하면 과금, 능력, 컨텍스트 제한은 모두 최종 응답한 그 모델을 기준으로 합니다. 이 모델은 응답 헤더에도 표시됩니다(4절 참조).2.4 무료 모델 규칙 (중요)
무료 모델은 fallback 옵션이 될 수 없습니다. 무료 모델은 주 모델로만 사용할 수 있으며, 백업 목록에 넣으면 조용히 건너뛰고 다음 항목으로 계속 진행합니다. 따라서 무료 모델을 fallback 목록에 넣지 마세요.대표적인 사용법: 무료 모델을 주 모델로 설정하고 유료 모델을 백업 목록에 넣습니다. 무료 주 모델이 할당량 / 빈도 제한에 걸리면 자동으로 백업 유료 모델로 폴백됩니다. 평소에는 무료 할당량으로 비용을 절감하고, 제한이 걸리면 매끄럽게 유료 모델로 전환하여 가용성을 보장합니다. 이는 fallback의 가장 일반적인 사용법 중 하나입니다.
3. OpenRouter / LiteLLM 와의 차이
모델 매핑과 폴백은 새로운 개념이 아니며, OpenRouter, LiteLLM 등도 유사한 기능을 제공합니다. AIHubMix의 차이점은 설정 비용이 가장 낮다는 데 있습니다:| 기능 | OpenRouter | LiteLLM | AIHubMix |
|---|---|---|---|
| 설정 방식 | 코드에서 models 배열 전달 | 자체 config.yaml proxy | 콘솔, API Key 단위 |
| 클라이언트 코드 수정 불필요 | ❌ | ❌ | ✅ |
| 자체 배포 / 자체 게이트웨이 불필요 | ✅ | ❌ | ✅ |
| 네이티브 프로토콜 보존(Claude / Gemini SDK) | ❌ | ❌ | ✅ |
| 최종 응답 모델 기준 과금 | ✅ | — | ✅ |
| API Key 단위 설정 | ❌ | ❌ | ✅ |
4. 설정과 검증
4.1 설정
- Key에서 별칭 매핑을 설정합니다: 좌측 별칭은 클라이언트가 실제로 보내는 모델명과 문자 단위로 일치해야 합니다.
- 동일한 Key에서 백업 모델 목록(순서가 있는 우선순위 목록)을 설정합니다.
- 백업 목록에는 유료 / 사용 가능 모델만 넣고, 무료 모델은 넣지 않습니다(건너뛰어집니다).
- 백업 목록의 모델은 해당 Key의 사용 가능 모델 범위 내에 있어야 합니다(범위를 벗어난 모델은 건너뛰어집니다).
4.2 검증 (로그를 뒤지기보다 응답 헤더를 먼저 확인)
문제를 조사할 때 클라이언트가 어떤 모델을 선택했는지만 보지 마세요. 가장 권위 있고 자동화 가능한 방법은 응답 헤더를 읽는 것입니다:X-Aihubmix-Fallback: true: 이번 요청에서 폴백이 발생했습니다(최종 모델 ≠ 주 모델일 때 추가됨).X-Aihubmix-Model: 이번에 실제로 응답했으며 그 기준으로 과금되는 모델.
5. 시나리오 1: Claude Desktop
Claude Desktop은Gateway를 통해 AIHubMix에 연동하며, 모델명 매핑의 대표적인 시나리오입니다.
이 절은 Claude Desktop의 기본 연동을 이미 완료했다고 가정합니다. 전체 연동 단계(다운로드 및 설치, 개발자 모드, Gateway 설정, auth scheme 등)는 Claude Desktop에서 AIHubMix 연동하기를 참조하세요. 이 절에서는 매핑과 폴백의 추가 설정만 다룹니다.
5.1 왜 매핑이 필요한가
Claude Desktop은Gateway(Anthropic-compatible) 방식으로 연동하며, 클라이언트가 Claude 스타일로 모델명을 제약하므로 모델명은 반드시 claude- 접두사를 사용해야 합니다.
그래서 모순이 생깁니다: 클라이언트 측에서는 claude- 스타일의 이름만 쓸 수 있지만, 당신이 실제로 호출하고 싶은 것은 gpt-5.5-pro, gemini-3.1-pro-preview 같은 것들입니다. 모델명 매핑은 바로 이를 위해 존재합니다. 클라이언트는 별칭 claude-g-p-t-5.5를 쓰고, AIHubMix 측이 실제 gpt-5.5-pro로 매핑합니다.
Claude Desktop은 Claude 네이티브 /v1/messages 인터페이스를 사용하므로, 이 문서의 예시에서는 매핑과 Fallback이 모두 적용됩니다.
5.2 AIHubMix 매핑과 폴백 설정
설정 예시:
5.3 Claude Desktop 모델 목록
Claude Desktop의Model list에 설정하는 것은 매핑 전 별칭입니다. 즉 Claude Desktop이 AIHubMix로 보내는 모델명이며, 실제 업스트림 모델명이 아닙니다.
Model ID는claude-접두사를 사용합니다.gpt,gemini,deepseek등 실제 모델 시리즈명을 직접 쓰지 말고,g-p-t,gemi,depsek같은 별칭을 사용할 수 있습니다.Model ID는 AIHubMix 매핑 좌측과 문자 단위로 일치해야 합니다. 그렇지 않으면 요청이 예상한 매핑에 적중하지 않고 오류 폴백 모델로 계속 진행될 수 있습니다.
6. 시나리오 2: 멀티모달 능력 보완
멀티모달 능력 보완은 「주 모델이 텍스트는 답변할 수 있지만 현재 입력 유형은 지원하지 않는」 시나리오를 처리하기 위한 것입니다. 예를 들어 클라이언트가 이미지나 동영상을 보냈는데 주 모델은 텍스트 입력 능력만 있는 경우, AIHubMix는 폴백 목록에서 해당 모달리티를 지원하는 모델을 계속 시도할 수 있습니다. 다음은 실제 테스트 경로입니다. 이 Key의 매핑과 fallback 설정은 다음과 같으며(아래 스크린샷 참조), 핵심은 fallback 목록에 텍스트 모델과 이미지 이해를 지원하는 모델이 함께 들어 있다는 점입니다:claude-g-l-m-4.6으로 표시됩니다. 이는 텍스트 입력만 지원하는 모델입니다. 사용자가 AIHubMix 모델 목록 페이지 스크린샷 한 장을 업로드하고 「이 웹사이트는 무엇을 하는 곳인가」라고 물었습니다. 요청에 이미지가 포함되어 있어 텍스트 모델은 이 입력을 직접 처리할 수 없었고, 그래서 fallback이 트리거되었습니다.
Google AI Studio/gemini-3.1-flash-image로, fallback 목록의 2번째입니다. 1번째인 gpt-5.4 역시 해당 이미지 입력을 지원하지 않아 이번 요청에 대해 재시도 가능한 오류를 계속 반환했고, 그래서 게이트웨이가 계속 아래로 내려가 이미지 이해를 지원하는 gemini-3.1-flash-image에 도달했습니다.
트리거 원인을 명확히: 여기서 보완이 일어난 것은 업스트림이 해당 이미지 입력에 대해 재시도 가능한 오류를 반환했고, 주 모델의 채널이 소진되었기 때문입니다. 「주 모델이 제한에 걸린 후 폴백」과 동일한 폴백 메커니즘이며, 트리거되는 오류 유형만 다릅니다(전자는 입력이 지원되지 않음, 후자는 할당량 / 빈도 제한).
이해와 생성을 구분할 것: 여기서 말하는 것은 이미지 / 동영상 이해 보완이지, 이미지 생성이나 동영상 생성이 아닙니다. 채팅 요청이 자동으로 생성 인터페이스로 바뀌지는 않습니다. 그림 그리기나 동영상 생성을 테스트하려면 해당 생성 인터페이스와 모델을 사용해야 합니다. 모델 능력은 AIHubMix 모델 페이지에 현재 표시된 Input Modalities를 기준으로 합니다.
7. 시나리오 3: 무료 모델 보완 (비용 절감 + 가용성 보장)
이는 fallback의 가장 일반적인 사용법 중 하나입니다: 무료 모델을 주 모델로 설정하고 유료 모델을 백업 목록에 넣습니다. 평소에는 요청이 모두 무료 모델로 가서 비용을 절감하고, 무료 주 모델이 할당량 / 빈도 제한에 걸리는 순간 게이트웨이가 자동으로 백업 유료 모델로 폴백하여 서비스 중단을 방지합니다. Key 설정 예시:- 무료 할당량이 아직 충분할 때는 요청이 주 모델
coding-glm-4.6-free로 응답되며 무료로 과금됩니다. - 무료 주 모델이 제한에 걸리면 자동으로
gpt-5.4로 폴백하고,gpt-5.4도 사용 불가능하면gemini-3.1-pro-preview를 다시 시도합니다. - 최종적으로 어떤 모델이 응답하든 그 모델 기준으로 과금합니다(2.3 참조).
주의: 무료 모델은 주 모델로만 사용할 수 있으며, fallback 목록에 넣을 수 없습니다(넣으면 건너뛰어집니다, 2.4 참조). 따라서 「무료 보완」의 올바른 방식은 무료를 주 모델로, 유료를 백업으로 두는 것이며, 그 반대가 아닙니다.검증 방식도 마찬가지로 응답 헤더를 보는 것입니다: 폴백이 발생하면
X-Aihubmix-Fallback: true가 반환되고, X-Aihubmix-Model이 최종 응답 모델을 표시합니다(4절 참조).
8. 지원하는 엔드포인트
모델 매핑과 오류 폴백은 현재 다음 인터페이스 범주를 지원합니다:| 인터페이스 범주 | Key 별칭 매핑 | 오류 폴백 Fallback |
|---|---|---|
OpenAI 호환 인터페이스(/v1/chat/completions, /v1/completions, /v1/embeddings, /v1/images/*, /v1/audio/transcriptions·/translations, /v1/rerank, /v1/moderations, /v1/edits 등) | ✅ | ✅ |
Claude 네이티브 /v1/messages | ✅ | ✅ |
OpenAI Responses /v1/responses | ✅ | ✅ |
기타 네이티브 패스스루 인터페이스(Gemini 네이티브, Ideogram, /v1/videos, /v1/audio/speech(TTS), Stability, OCR, /predictions 등) | ❌ | ❌ |
특정 채널 패스스루 /v1/proxy/{channelid}/* | ❌ | ❌ |
리소스 ID 기반 조회 / 파일류(GET /v1/responses/{id}, /v1/videos/{id}, files 등, 요청 본문에 model 미포함) | ❌ | ❌ |
- 모델 매핑과 오류 폴백은 OpenAI 호환 인터페이스, Claude 네이티브
/v1/messages, OpenAI Responses/v1/responses세 가지 범주의 인터페이스를 지원합니다. - 기타 네이티브 패스스루 인터페이스(Gemini 네이티브, Ideogram, 동영상, TTS, Stability, OCR, predictions 등), 특정 채널 패스스루, 그리고 리소스 ID 기반 조회 / 파일류 인터페이스는 현재 지원하지 않습니다.
- Claude Desktop은 Claude 네이티브
/v1/messages를 사용하므로, 이 문서의 예시에서는 매핑과 Fallback이 모두 적용됩니다.
9. 자주 묻는 질문 FAQ
Q: Claude Desktop에서 model not found가 표시되면 어떻게 하나요? A: Claude Desktop의Model ID가 AIHubMix 매핑 좌측과 문자 단위로 일치하는지 확인하세요. 일치하지 않으면 매핑에 적중하지 않습니다.
Q: 폴백이 과금에 영향을 주나요?
A: 최종 응답 모델 기준으로 과금합니다. 최종적으로 어떤 모델이 응답하든 그 모델의 가격, 능력, 컨텍스트 제한으로 계산합니다.
Q: 이번 요청이 폴백을 거쳤는지 어떻게 확인하나요?
A: 응답 헤더 X-Aihubmix-Fallback: true(폴백 발생)와 X-Aihubmix-Model(최종 응답 모델)을 확인하세요, 4절 참조.
Q: 어떤 오류가 폴백을 트리거하고, 어떤 오류는 트리거하지 않나요?
A: 2.2의 대조표를 참조하세요. 간단히 말해 업스트림 재시도 가능 실패, 채널 소진, 응답 미시작일 때만 폴백됩니다. 특정 채널 지정, 응답이 이미 시작됨, 클라이언트 연결 끊김 / 타임아웃, Key / 사용자 단위 오류는 모두 폴백되지 않습니다.
Q: 무료 모델을 fallback 목록에 넣을 수 있나요?
A: 넣을 수 없습니다, 건너뛰어집니다. 무료 모델은 주 모델로만 사용할 수 있습니다.
Q: OpenRouter / LiteLLM의 model alias / fallback과 무엇이 다른가요?
A: AIHubMix는 Key 단위, 플랫폼 호스팅이며, 콘솔에서 한 번만 설정하면 적용되고 클라이언트 코드를 수정할 필요도, 직접 게이트웨이를 구축할 필요도 없습니다. 자세한 내용은 3절을 참조하세요.
관련 리소스
- Claude Desktop에서 AIHubMix 연동하기: 개발자 모드, Gateway 설정, auth scheme 등 전체 단계.
- AIHubMix 모델 페이지: 모델 이름, 가격,
Input Modalities조회. - LiteLLM에서 AIHubMix 연동하기: 직접 게이트웨이 구축 + 모델 매핑 / 폴백이 필요할 때의 참고 자료.