> ## Documentation Index > Fetch the complete documentation index at: https://docs.arouter.ai/llms.txt > Use this file to discover all available pages before exploring further. # 모델 라우팅 > ARouter가 provider/model 형식, `auto`, 그리고 순서가 지정된 후보 모델 목록을 사용하여 올바른 프로바이더로 요청을 라우팅하는 방법. ## `provider/model` 형식 OpenAI 호환 엔드포인트(`/v1/chat/completions`, `/v1/embeddings`)를 사용할 때, `provider/model` 형식으로 모델을 지정합니다: ```json theme={null} { "model": "anthropic/claude-sonnet-4.6", "messages": [{"role": "user", "content": "Hello!"}] } ``` ARouter는 프로바이더 접두사를 파싱하고, 올바른 업스트림으로 요청을 라우팅하며, 전달 전에 `model` 필드를 프로바이더의 네이티브 형식으로 재작성합니다. ## 예시 | 전송 내용 | 프로바이더 | 업스트림 모델 | | ------------------------------ | ----------- | -------------------- | | `openai/gpt-5.4` | OpenAI | `gpt-5.4` | | `anthropic/claude-sonnet-4.6` | Anthropic | `claude-sonnet-4.6` | | `google/gemini-2.5-flash` | Google | `gemini-2.5-flash` | | `deepseek/deepseek-v3.2` | DeepSeek | `deepseek-v3.2` | | `x-ai/grok-4.20` | xAI | `grok-4.20` | | `mistralai/mistral-large-2512` | Mistral | `mistral-large-2512` | | `meta-llama/llama-4-maverick` | Meta | `llama-4-maverick` | | `gpt-5.4` | OpenAI（기본값） | `gpt-5.4` | 프로바이더 접두사를 생략하면 ARouter는 기본적으로 **OpenAI**를 사용합니다. 따라서 `"model": "gpt-5.4"`는 `"model": "openai/gpt-5.4"`와 동일합니다. ## 네이티브 SDK 엔드포인트 자체 SDK 형식을 가진 프로바이더의 경우 네이티브 엔드포인트를 직접 사용합니다. 프로바이더는 model 필드가 아닌 엔드포인트 경로로 결정됩니다: | SDK | 엔드포인트 | 모델 형식 | | --------- | --------------------------------------------- | ------------------------- | | Anthropic | `POST /v1/messages` | 네이티브: `claude-sonnet-4.6` | | Gemini | `POST /v1beta/models/{model}:generateContent` | 네이티브: `gemini-2.5-flash` | | MiniMax | `POST /v1/text/chatcompletion_v2` | 네이티브: `minimax-m2.7` | 네이티브 엔드포인트는 `provider/model` 접두사를 **사용하지 않습니다**——엔드포인트 경로에 이미 프로바이더가 내포되어 있으므로 프로바이더의 원본 모델 이름을 사용합니다. ## 범용 프로바이더 프록시 모든 프로바이더에 대해 범용 프록시 형식을 사용할 수 있습니다: ``` POST /{provider}/v1/chat/completions ``` 예시: * `POST /openai/v1/chat/completions` → OpenAI로 프록시 * `POST /deepseek/v1/chat/completions` → DeepSeek으로 프록시 * `POST /anthropic/v1/messages` → Anthropic으로 프록시 model 필드 파싱을 우회하고 어떤 프로바이더가 요청을 받을지 명시적으로 제어하고 싶을 때 유용합니다. ## 자동 라우팅 `model`을 `"auto"`로 설정하면 ARouter가 프롬프트에 가장 적합한 모델을 자동으로 선택합니다. 모델 설정이 필요 없습니다. ```json theme={null} { "model": "auto", "messages": [{ "role": "user", "content": "Explain quantum entanglement in simple terms" }] } ``` ### 작동 원리 1. ARouter의 라우팅 서비스가 요청을 분석합니다 (프롬프트 복잡도, 작업 유형, 필요한 모달리티 등) 2. 비용 효율성과 품질을 기반으로 사용 가능한 정상 프로바이더 중 최적 모델을 선택합니다 3. 선택된 모델로 요청을 전달합니다 4. 응답에는 실제로 사용된 모델을 나타내는 `model` 필드가 포함됩니다 ### 허용 모델 제한 `auto-router` 플러그인을 사용하여 와일드카드 패턴으로 `auto`가 선택할 수 있는 모델을 제한합니다: ```typescript theme={null} const response = await client.chat.completions.create({ model: "auto", messages: [{ role: "user", content: "Explain quantum entanglement" }], // @ts-ignore plugins: [ { id: "auto-router", allowed_models: ["anthropic/*", "openai/gpt-5.4"], }, ], }); ``` ```python theme={null} response = client.chat.completions.create( model="auto", messages=[{"role": "user", "content": "Explain quantum entanglement"}], extra_body={ "plugins": [ { "id": "auto-router", "allowed_models": ["anthropic/*", "openai/gpt-5.4"], } ] }, ) ``` ```bash theme={null} curl https://api.arouter.ai/v1/chat/completions \ -H "Authorization: Bearer lr_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "auto", "messages": [{"role": "user", "content": "Explain quantum entanglement"}], "plugins": [ { "id": "auto-router", "allowed_models": ["anthropic/*", "openai/gpt-5.4"] } ] }' ``` **패턴 문법:** | 패턴 | 매칭 | | ---------------- | ----------------------------- | | `anthropic/*` | 모든 Anthropic 모델 | | `openai/gpt-5*` | 모든 GPT-5 변형 | | `google/*` | 모든 Google 모델 | | `openai/gpt-5.4` | 정확한 일치만 | | `*/claude-*` | 모델 이름에 "claude"가 포함된 모든 프로바이더 | ```json theme={null} { "id": "chatcmpl-xxx", "model": "anthropic/claude-sonnet-4.6", "choices": [ { "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 15, "completion_tokens": 120, "total_tokens": 135 } } ``` 실제로 사용된 모델을 확인하려면 항상 `response.model`을 확인하세요. ### 코드 예시 ```python theme={null} from openai import OpenAI client = OpenAI( base_url="https://api.arouter.ai/v1", api_key="lr_live_xxxx", ) response = client.chat.completions.create( model="auto", messages=[{"role": "user", "content": "Explain quantum entanglement in simple terms"}], ) print(response.choices[0].message.content) print("Model used:", response.model) ``` ```typescript theme={null} import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.arouter.ai/v1", apiKey: "lr_live_xxxx", }); const response = await client.chat.completions.create({ model: "auto", messages: [{ role: "user", content: "Explain quantum entanglement in simple terms" }], }); console.log(response.choices[0].message.content); console.log("Model used:", response.model); ``` ```go theme={null} resp, err := client.CreateChatCompletion(ctx, arouter.ChatCompletionRequest{ Model: "auto", Messages: []arouter.Message{ {Role: "user", Content: "Explain quantum entanglement in simple terms"}, }, }) if err != nil { log.Fatal(err) } fmt.Println(resp.Choices[0].Message.Content) fmt.Println("Model used:", resp.Model) ``` ```bash theme={null} curl https://api.arouter.ai/v1/chat/completions \ -H "Authorization: Bearer lr_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "auto", "messages": [{"role": "user", "content": "Explain quantum entanglement in simple terms"}] }' ``` ### 사용 사례 * **범용 앱** — 사용자가 어떤 종류의 프롬프트를 보낼지 모를 때 * **비용 최적화** — ARouter가 간단한 작업을 효율적인 모델로 자동 라우팅 * **제로 설정 프로토타이핑** — 특정 모델을 선택하지 않고 즉시 시작 * **적응형 라우팅** — 먼저 ARouter에게 맡기고, 명시적 제어가 필요할 때만 후보 목록으로 전환 ### 제한 사항 * 자동 라우팅은 표준 `messages` 요청 형식을 사용합니다 * 자동 라우팅은 계정에서 사용 가능한 모델 중에서 선택합니다 * 스트리밍은 `"model": "auto"`에서 완전히 지원됩니다 * ARouter가 선택한 모델의 정상 요금을 지불합니다. 추가 라우팅 요금은 없습니다 * 선택된 모델은 항상 응답의 `model` 필드에 반영됩니다 *** ## 후보 모델 목록 `models` 배열과 `route`를 함께 사용하여 ARouter가 순서가 지정된 후보 목록을 순차적으로 처리하도록 합니다. ```json theme={null} { "models": [ "anthropic/claude-opus-4.5", "openai/gpt-5.4", "google/gemini-2.5-flash" ], "route": "fallback", "messages": [{ "role": "user", "content": "Hello!" }] } ``` ### 작동 원리 1. ARouter가 목록의 첫 번째 모델을 시도합니다 2. 요청을 처리할 수 없는 경우(프로바이더 오류, 속도 제한, 키 사용 불가), 다음 모델로 이동합니다 3. 모든 모델이 실패하면 ARouter는 마지막 실패 이유를 포함한 오류를 반환합니다 ### 라우팅 동작 | 트리거 | 동작 | | ----------- | ------------- | | 프로바이더 사용 불가 | 다음 모델로 이동 | | 속도 제한(429) | 다음 모델로 이동 | | 모델을 찾을 수 없음 | 다음 모델로 이동 | | 잘못된 요청(400) | 중지하고 요청 오류 반환 | ### 파티션 동작 제어 기본적으로 후보 목록을 사용할 때, 엔드포인트는 모델별로 그룹화됩니다——첫 번째 모델의 엔드포인트는 항상 두 번째 모델보다 먼저 시도됩니다. `provider.sort.partition`으로 이 동작을 변경할 수 있습니다: ```json theme={null} { "models": [ "anthropic/claude-sonnet-4.6", "openai/gpt-5.4", "google/gemini-2.5-flash" ], "route": "fallback", "messages": [{ "role": "user", "content": "Hello!" }], "provider": { "sort": { "by": "throughput", "partition": "none" } } } ``` `partition: "none"`을 설정하면 모든 후보 모델에 걸쳐 전역적으로 엔드포인트를 정렬합니다——목록 순서에 관계없이 현재 가장 빠른 모델을 사용하고 싶을 때 유용합니다. 전체 참조는 [프로바이더 라우팅](/ko/provider-routing#advanced-sorting-with-partition)을 참조하세요. ### OpenAI SDK에서 후보 목록 사용 OpenAI SDK에는 네이티브 `models` 파라미터가 없습니다. `extra_body`를 사용하여 전달합니다: ```python theme={null} from openai import OpenAI client = OpenAI( base_url="https://api.arouter.ai/v1", api_key="lr_live_xxxx", ) response = client.chat.completions.create( model="anthropic/claude-opus-4.5", # 첫 번째 후보 messages=[{"role": "user", "content": "Hello!"}], extra_body={ "models": [ "anthropic/claude-opus-4.5", "openai/gpt-5.4", "google/gemini-2.5-flash", ], "route": "fallback", }, ) print(response.choices[0].message.content) ``` ```typescript theme={null} import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.arouter.ai/v1", apiKey: "lr_live_xxxx", }); const response = await client.chat.completions.create({ model: "anthropic/claude-opus-4.5", // 첫 번째 후보 messages: [{ role: "user", content: "Hello!" }], // @ts-ignore — extra_body는 타입 정의에 없습니다 models: [ "anthropic/claude-opus-4.5", "openai/gpt-5.4", "google/gemini-2.5-flash", ], route: "fallback", }); console.log(response.choices[0].message.content); ``` ```bash theme={null} curl https://api.arouter.ai/v1/chat/completions \ -H "Authorization: Bearer lr_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "models": [ "anthropic/claude-opus-4.5", "openai/gpt-5.4", "google/gemini-2.5-flash" ], "route": "fallback", "messages": [{"role": "user", "content": "Hello!"}] }' ``` ## 어시스턴트 프리필 ARouter는 모델이 부분적인 응답을 완성하도록 요청하는 기능을 지원합니다. `messages` 배열 끝에 `role: "assistant"` 메시지를 포함시켜 중단된 곳에서 계속할 수 있습니다: ```json theme={null} { "model": "anthropic/claude-sonnet-4.6", "messages": [ { "role": "user", "content": "Name 3 popular programming languages." }, { "role": "assistant", "content": "1." } ] } ``` 모델은 프리필된 어시스턴트 메시지에서 계속 생성합니다. 이 기법은 다음에 유용합니다: * 특정 출력 형식 강제 * 멀티턴 완성 재개 * 모델을 특정 응답 구조로 유도 모든 모델이 어시스턴트 프리필을 지원하는 것은 아닙니다. Anthropic Claude와 대부분의 오픈소스 모델은 지원합니다. OpenAI 모델은 제한적으로 지원합니다. ## 라우팅 내부 동작 원리 ``` 1. model 필드 파싱 → 프로바이더 ID 추출 2. API key 권한 확인 → 해당 프로바이더가 허용되었는가? 3. 라우터 서비스 호출 → 리전 선택, 풀에서 정상 키 선택 4. model 필드 재작성 → 프로바이더 접두사 제거 5. 리버스 프록시 → 프로바이더의 API key로 업스트림에 전달 6. 응답 스트리밍 반환 → 사용량 비동기 기록 ``` ARouter는 프로바이더 API key 주입, 헬스 체크, 페일오버를 완전히 투명하게 처리합니다. 애플리케이션은 업스트림 프로바이더의 자격 증명을 절대 볼 수 없습니다.