> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # 모델 매핑과 폴백 > AIHubMix 콘솔에서 API Key마다 모델명 매핑과 오류 시 폴백을 설정하세요: 클라이언트의 모델 별칭을 실제 업스트림 모델로 변환하고, 주 모델 실패 시 자동으로 백업 모델로 전환하며, 최종 응답 모델 기준으로 과금하고, 클라이언트 코드는 전혀 수정하지 않습니다. > 업스트림 장애가 당신의 장애가 되지 않게 하세요. AIHubMix는 콘솔에서 한 번만 설정하면 적용되며 클라이언트 코드를 수정할 필요가 없는 **Key 단위**의 두 가지 기능을 제공합니다: * **모델명 매핑**(Model Mapping)은 게이트웨이 계층에서 클라이언트 요청의 모델 별칭을 실제 업스트림 모델로 변환하는 기능입니다. * **오류 시 폴백 모델**(Fallback)은 주 모델 호출이 실패했을 때 게이트웨이가 미리 설정한 우선순위 순서대로 자동으로 백업 모델을 시도하는, 클라이언트가 인지하지 못하는 기능입니다. 이 두 기능은 AIHubMix를 통해 연동하는 모든 클라이언트와 플랫폼에 적용됩니다. 업스트림 채널의 일시적 장애, 여러 모델 간 재해 복구가 필요한 경우, 또는 클라이언트가 특정 형식의 모델명만 인식하는 경우 등은 과거에는 코드를 수정하거나 직접 게이트웨이를 구축해야 해결할 수 있었습니다. 이제는 AIHubMix의 Key 설정에서 처리할 수 있으며, 클라이언트 코드를 수정할 필요도, 직접 게이트웨이를 구축할 필요도 없습니다. AIHubMix는 Key 단위로 모델명 매핑과 오류 시 폴백을 설정할 수 있으며, 최종 응답 모델 기준으로 과금합니다. 두 기능 모두 [AIHubMix Key 관리 페이지](https://console.aihubmix.com/token)에서 개별 API Key에 대해 설정합니다. Key를 생성하거나 편집할 때 패널의 `Model name mapping` 과 `Fallback models on error` 두 섹션에서 각각 설정합니다. AIHubMix Key 생성 패널에서 모델명 매핑과 폴백 설정 *** ## 1. 모델명 매핑 (Model Mapping) 모델명 매핑은 「클라이언트가 보는 모델명」과 「AIHubMix가 실제로 호출하는 모델」이 일치하지 않는 문제를 처리하기 위한 것입니다. 이는 **Key 단위**(per-key)의 별칭 변환으로, 요청의 별칭을 Key에 설정한 대상 모델로 변환합니다. > 대상 모델은 채널이 선택된 후 플랫폼 내부에서 다시 한 번 채널 단위로 실제 업스트림 모델로 매핑됩니다. 이 계층은 사용자에게 투명하며 설정할 필요가 없습니다. 당신은 「별칭 → 대상 모델」 계층만 신경 쓰면 됩니다. 예시: | 클라이언트 요청 모델명(별칭) | AIHubMix 대상 모델 | | ---------------- | ------------------------ | | `my-gpt` | `gpt-5.5` | | `my-fast` | `gemini-3.1-pro-preview` | | `my-coder` | `deepseek-v4-flash` | | `my-glm` | `coding-glm-5.2-free` | > 위 표의 모델명은 모두 [AIHubMix 모델 페이지](https://aihubmix.com/models)에서 조회할 수 있습니다. 일반적인 용도: * 클라이언트가 모델명 형식을 제한하는 경우. 예를 들어 Claude Desktop은 모델명이 Claude 스타일을 따르도록 요구합니다([5절](#5-시나리오-1-claude-desktop) 참조). * 복잡한 모델 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 트리거 조건 (모두 충족해야 폴백) **다음 조건이 모두 성립**할 때만 폴백이 발생합니다: 1. Key에 비어 있지 않은 백업 모델 목록이 설정되어 있습니다. 2. 주 모델의 **모든 채널을 시도했고, 모두 「재시도 가능한 오류」로 실패**했습니다(채널 소진). 3. **응답이 아직 반환되기 시작하지 않았습니다**(첫 바이트 / header가 아직 클라이언트로 전송되지 않음). 4. 오류가 Key / 사용자 단위 오류가 아닙니다(아래 [2.2 대조표](#2-2-폴백되는-경우와-되지-않는-경우) 참조). 다음 백업 모델로 전환한 후, 게이트웨이는 새 모델로 채널을 다시 선택하여 재시도합니다. ### 2.2 폴백되는 경우와 되지 않는 경우 | 상황 | 폴백 여부 | | -------------------------------------------------------- | :-------------------: | | 주 모델 전 채널 「재시도 가능 실패」, 응답 미시작 | ✅ 폴백 | | 특정 채널을 지정한 경우(Key 접미사 `sk-xxx-{id}`, `/v1/proxy/{id}/*`) | ❌ | | 응답이 이미 반환되기 시작(스트리밍에서 첫 바이트가 나감) | ❌ | | 클라이언트 연결 끊김 / 요청 타임아웃 | ❌ | | 당신의 AIHubMix Key 잔액 부족 / 무효 / 만료 / 비활성화 | ❌ | | 계정 차단 / 리스크 관리 키워드 적중 | ❌ | | 무료 주 모델이 할당량 / 빈도 제한에 걸림 | ✅ 백업 유료 모델로 폴백 | | 백업 목록의 **무료 모델** | ⏭️ 해당 항목 건너뛰고 다음으로 계속 | | 백업 목록 중 Key의 사용 가능 범위를 벗어난 모델 | ⏭️ 건너뜀 | > 참고: 여기서 「Key 무효」는 **당신 자신의 AIHubMix Key**이 무효가 된 것을 의미하며, 이 경우 폴백되지 않습니다. 어떤 **업스트림 채널**의 key가 망가진 경우라면 게이트웨이가 채널을 교체하며, 채널이 소진된 후에는 **여전히** 폴백이 가능합니다. 둘을 혼동하지 마세요. ### 2.3 과금 기준 **최종 응답 모델 기준으로 과금합니다.** 최종적으로 폴백 모델이 응답하면 과금, 능력, 컨텍스트 제한은 모두 최종 응답한 그 모델을 기준으로 합니다. 이 모델은 응답 헤더에도 표시됩니다([4절](#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 단위 설정 | ❌ | ❌ | ✅ | 한마디로: **직접 게이트웨이를 구축할 필요도, 클라이언트 코드를 한 줄도 수정할 필요도 없이, Key에 한 번만 설정하면 적용됩니다.** *** ## 4. 설정과 검증 ### 4.1 설정 1. **Key**에서 별칭 매핑을 설정합니다: 좌측 별칭은 클라이언트가 실제로 보내는 모델명과 **문자 단위로 일치**해야 합니다. 2. **동일한 Key**에서 백업 모델 목록(순서가 있는 우선순위 목록)을 설정합니다. 3. 백업 목록에는 **유료 / 사용 가능 모델만 넣고, 무료 모델은 넣지 않습니다**(건너뛰어집니다). 4. 백업 목록의 모델은 해당 Key의 사용 가능 모델 범위 내에 있어야 합니다(범위를 벗어난 모델은 건너뛰어집니다). ### 4.2 검증 (로그를 뒤지기보다 응답 헤더를 먼저 확인) 문제를 조사할 때 **클라이언트가 어떤 모델을 선택했는지만 보지 마세요.** 가장 권위 있고 자동화 가능한 방법은 응답 헤더를 읽는 것입니다: * `X-Aihubmix-Fallback: true`: 이번 요청에서 폴백이 발생했습니다(최종 모델 ≠ 주 모델일 때 추가됨). * `X-Aihubmix-Model`: 이번에 실제로 응답했으며 그 기준으로 과금되는 모델. curl 검증 예시: ```bash theme={null} curl -i https://aihubmix.com/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"my-gpt","messages":[{"role":"user","content":"hi"}]}' \ | grep -i -E 'x-aihubmix-(model|fallback)' ``` 콘솔 로그를 통해 요청 모델, 매핑 후 주 모델, 최종 응답 모델을 교차 검증할 수 있습니다. *** ## 5. 시나리오 1: Claude Desktop Claude Desktop은 `Gateway`를 통해 AIHubMix에 연동하며, 모델명 매핑의 대표적인 시나리오입니다. 이 절은 Claude Desktop의 기본 연동을 이미 완료했다고 가정합니다. 전체 연동 단계(다운로드 및 설치, 개발자 모드, Gateway 설정, auth scheme 등)는 [Claude Desktop에서 AIHubMix 연동하기](https://docs.aihubmix.com/cn/api/claude-desktop)를 참조하세요. 이 절에서는 매핑과 폴백의 추가 설정만 다룹니다. ### 5.1 왜 매핑이 필요한가 Claude Desktop은 `Gateway`(Anthropic-compatible) 방식으로 연동하며, 클라이언트가 Claude 스타일로 모델명을 제약하므로 모델명은 반드시 `claude-` 접두사를 사용해야 합니다. 그래서 모순이 생깁니다: 클라이언트 측에서는 `claude-` 스타일의 이름만 쓸 수 있지만, 당신이 실제로 호출하고 싶은 것은 `gpt-5.5`, `gemini-3.1-pro-preview` 같은 것들입니다. **모델명 매핑은 바로 이를 위해 존재합니다.** 클라이언트는 별칭 `claude-g-p-t-5.5`를 쓰고, AIHubMix 측이 실제 `gpt-5.5`로 매핑합니다. > Claude Desktop은 Claude 네이티브 `/v1/messages` 인터페이스를 사용하므로, 이 문서의 예시에서는 **매핑과 Fallback이 모두 적용**됩니다. ### 5.2 AIHubMix 매핑과 폴백 설정 설정 예시: ```text theme={null} claude-g-p-t-5.5 -> gpt-5.5 claude-gemi-3.1 -> gemini-3.1-pro-preview claude-depsek-v4 -> deepseek-v4-flash fallback: 1. gpt-5.4 2. gemini-3.1-pro-preview ``` AIHubMix 백엔드에서 모델명 매핑과 Fallback 폴백 목록 설정 ### 5.3 Claude Desktop 모델 목록 Claude Desktop의 `Model list`에 설정하는 것은 **매핑 전 별칭**입니다. 즉 Claude Desktop이 AIHubMix로 보내는 모델명이며, 실제 업스트림 모델명이 아닙니다. Claude Desktop Model list에 매핑 전 모델 별칭 설정 설정이 완료되면 Claude Desktop의 모델 드롭다운에 해당 모델이 나타납니다: Claude Desktop 모델 드롭다운에 설정한 별칭 모델이 나타남 명명 권장 사항: * `Model ID`는 `claude-` 접두사를 사용합니다. * `gpt`, `gemini`, `deepseek` 등 실제 모델 시리즈명을 직접 쓰지 말고, `g-p-t`, `gemi`, `depsek` 같은 별칭을 사용할 수 있습니다. * `Model ID`는 AIHubMix 매핑 좌측과 **문자 단위로 일치**해야 합니다. 그렇지 않으면 요청이 예상한 매핑에 적중하지 않고 오류 폴백 모델로 계속 진행될 수 있습니다. *** ## 6. 시나리오 2: 멀티모달 능력 보완 멀티모달 능력 보완은 「주 모델이 텍스트는 답변할 수 있지만 현재 입력 유형은 지원하지 않는」 시나리오를 처리하기 위한 것입니다. 예를 들어 클라이언트가 이미지나 동영상을 보냈는데 주 모델은 텍스트 입력 능력만 있는 경우, AIHubMix는 폴백 목록에서 해당 모달리티를 지원하는 모델을 계속 시도할 수 있습니다. 다음은 실제 테스트 경로입니다. 이 Key의 매핑과 fallback 설정은 다음과 같으며(아래 스크린샷 참조), 핵심은 fallback 목록에 텍스트 모델과 이미지 이해를 지원하는 모델이 함께 들어 있다는 점입니다: ```text theme={null} claude-g-l-m-4.6 -> coding-glm-5.2-free claude-g-p-t-5.5 -> gpt-5.5 claude-gemi-3.1 -> gemini-3.1-pro-preview fallback: 1. gpt-5.4 2. gemini-3.1-flash-image 3. veo-3.1-lite-generate-preview ``` Claude Desktop에서 선택한 모델은 `claude-g-l-m-4.6`으로 표시됩니다. 이는 텍스트 입력만 지원하는 모델입니다. 사용자가 AIHubMix 모델 목록 페이지 스크린샷 한 장을 업로드하고 「이 웹사이트는 무엇을 하는 곳인가」라고 물었습니다. 요청에 이미지가 포함되어 있어 텍스트 모델은 이 입력을 직접 처리할 수 없었고, 그래서 fallback이 트리거되었습니다. Claude Desktop에서 이미지 업로드 후 보완 모델이 결과를 반환 AIHubMix 로그를 보면 이번에 최종적으로 실제 호출된 것은 `Google AI Studio/gemini-3.1-flash-image`로, fallback 목록의 2번째입니다. 1번째인 `gpt-5.4` 역시 해당 이미지 입력을 지원하지 않아 이번 요청에 대해 재시도 가능한 오류를 계속 반환했고, 그래서 게이트웨이가 계속 아래로 내려가 이미지 이해를 지원하는 `gemini-3.1-flash-image`에 도달했습니다. AIHubMix 로그에서 요청이 최종적으로 이미지 이해를 지원하는 폴백 모델 gemini-3.1-flash-image로 라우팅됨을 표시 > **트리거 원인을 명확히**: 여기서 보완이 일어난 것은 **업스트림이 해당 이미지 입력에 대해 재시도 가능한 오류를 반환했고, 주 모델의 채널이 소진되었기** 때문입니다. 「주 모델이 제한에 걸린 후 폴백」과 동일한 폴백 메커니즘이며, 트리거되는 오류 유형만 다릅니다(전자는 입력이 지원되지 않음, 후자는 할당량 / 빈도 제한). > > **이해와 생성을 구분할 것**: 여기서 말하는 것은 **이미지 / 동영상 이해** 보완이지, **이미지 생성이나 동영상 생성**이 아닙니다. 채팅 요청이 자동으로 생성 인터페이스로 바뀌지는 않습니다. 그림 그리기나 동영상 생성을 테스트하려면 해당 생성 인터페이스와 모델을 사용해야 합니다. 모델 능력은 AIHubMix 모델 페이지에 현재 표시된 `Input Modalities`를 기준으로 합니다. *** ## 7. 시나리오 3: 무료 모델 보완 (비용 절감 + 가용성 보장) 이는 fallback의 가장 일반적인 사용법 중 하나입니다: **무료 모델을 주 모델로 설정**하고 **유료 모델을 백업 목록에 넣습니다.** 평소에는 요청이 모두 무료 모델로 가서 비용을 절감하고, 무료 주 모델이 할당량 / 빈도 제한에 걸리는 순간 게이트웨이가 자동으로 백업 유료 모델로 폴백하여 서비스 중단을 방지합니다. Key 설정 예시: ```text theme={null} 주 모델(무료): coding-glm-5.2-free fallback: 1. gpt-5.4 2. gemini-3.1-pro-preview ``` 동작: * 무료 할당량이 아직 충분할 때는 요청이 주 모델 `coding-glm-5.2-free`로 응답되며 무료로 과금됩니다. * 무료 주 모델이 제한에 걸리면 자동으로 `gpt-5.4`로 폴백하고, `gpt-5.4`도 사용 불가능하면 `gemini-3.1-pro-preview`를 다시 시도합니다. * 최종적으로 어떤 모델이 응답하든 **그 모델 기준으로 과금**합니다([2.3](#2-3-과금-기준) 참조). > **주의**: 무료 모델은 주 모델로만 사용할 수 있으며, **fallback 목록에 넣을 수 없습니다**(넣으면 건너뛰어집니다, [2.4](#2-4-무료-모델-규칙-중요) 참조). 따라서 「무료 보완」의 올바른 방식은 무료를 주 모델로, 유료를 백업으로 두는 것이며, 그 반대가 아닙니다. 검증 방식도 마찬가지로 응답 헤더를 보는 것입니다: 폴백이 발생하면 `X-Aihubmix-Fallback: true`가 반환되고, `X-Aihubmix-Model`이 최종 응답 모델을 표시합니다([4절](#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절](#4-설정과-검증) 참조. **Q: 어떤 오류가 폴백을 트리거하고, 어떤 오류는 트리거하지 않나요?** A: [2.2의 대조표](#2-2-폴백되는-경우와-되지-않는-경우)를 참조하세요. 간단히 말해 업스트림 재시도 가능 실패, 채널 소진, 응답 미시작일 때만 폴백됩니다. 특정 채널 지정, 응답이 이미 시작됨, 클라이언트 연결 끊김 / 타임아웃, Key / 사용자 단위 오류는 모두 폴백되지 않습니다. **Q: 무료 모델을 fallback 목록에 넣을 수 있나요?** A: 넣을 수 없습니다, 건너뛰어집니다. 무료 모델은 주 모델로만 사용할 수 있습니다. **Q: OpenRouter / LiteLLM의 model alias / fallback과 무엇이 다른가요?** A: AIHubMix는 **Key 단위, 플랫폼 호스팅**이며, 콘솔에서 한 번만 설정하면 적용되고 클라이언트 코드를 수정할 필요도, 직접 게이트웨이를 구축할 필요도 없습니다. 자세한 내용은 [3절](#3-openrouter-/-litellm-와의-차이)을 참조하세요. *** ## 관련 리소스 * [Claude Desktop에서 AIHubMix 연동하기](https://docs.aihubmix.com/cn/api/claude-desktop): 개발자 모드, Gateway 설정, auth scheme 등 전체 단계. * [AIHubMix 모델 페이지](https://aihubmix.com/models): 모델 이름, 가격, `Input Modalities` 조회. * [LiteLLM에서 AIHubMix 연동하기](https://docs.aihubmix.com/cn/clients/LiteLLM): 직접 게이트웨이 구축 + 모델 매핑 / 폴백이 필요할 때의 참고 자료.