모델 라우팅

`provider/model` 형식

OpenAI 호환 엔드포인트(/v1/chat/completions, /v1/embeddings)를 사용할 때, provider/model 형식으로 모델을 지정합니다:

{
  "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가 프롬프트에 가장 적합한 모델을 자동으로 선택합니다. 모델 설정이 필요 없습니다.

{
  "model": "auto",
  "messages": [{ "role": "user", "content": "Explain quantum entanglement in simple terms" }]
}

작동 원리

ARouter의 라우팅 서비스가 요청을 분석합니다 (프롬프트 복잡도, 작업 유형, 필요한 모달리티 등)
비용 효율성과 품질을 기반으로 사용 가능한 정상 프로바이더 중 최적 모델을 선택합니다
선택된 모델로 요청을 전달합니다
응답에는 실제로 사용된 모델을 나타내는 model 필드가 포함됩니다

허용 모델 제한

auto-router 플러그인을 사용하여 와일드카드 패턴으로 auto가 선택할 수 있는 모델을 제한합니다:

TypeScript
Python
cURL

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"],
    },
  ],
});

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"],
            }
        ]
    },
)

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”가 포함된 모든 프로바이더

{
  "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 (OpenAI)
Node.js (OpenAI)
Go
cURL

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)

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);

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)

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가 순서가 지정된 후보 목록을 순차적으로 처리하도록 합니다.

{
  "models": [
    "anthropic/claude-opus-4.5",
    "openai/gpt-5.4",
    "google/gemini-2.5-flash"
  ],
  "route": "fallback",
  "messages": [{ "role": "user", "content": "Hello!" }]
}

작동 원리

ARouter가 목록의 첫 번째 모델을 시도합니다
요청을 처리할 수 없는 경우(프로바이더 오류, 속도 제한, 키 사용 불가), 다음 모델로 이동합니다
모든 모델이 실패하면 ARouter는 마지막 실패 이유를 포함한 오류를 반환합니다

라우팅 동작

트리거	동작
프로바이더 사용 불가	다음 모델로 이동
속도 제한(429)	다음 모델로 이동
모델을 찾을 수 없음	다음 모델로 이동
잘못된 요청(400)	중지하고 요청 오류 반환

파티션 동작 제어

기본적으로 후보 목록을 사용할 때, 엔드포인트는 모델별로 그룹화됩니다——첫 번째 모델의 엔드포인트는 항상 두 번째 모델보다 먼저 시도됩니다. provider.sort.partition으로 이 동작을 변경할 수 있습니다:

{
  "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"을 설정하면 모든 후보 모델에 걸쳐 전역적으로 엔드포인트를 정렬합니다——목록 순서에 관계없이 현재 가장 빠른 모델을 사용하고 싶을 때 유용합니다. 전체 참조는 프로바이더 라우팅을 참조하세요.

OpenAI SDK에서 후보 목록 사용

OpenAI SDK에는 네이티브 models 파라미터가 없습니다. extra_body를 사용하여 전달합니다:

Python (OpenAI)
Node.js (OpenAI)
cURL

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)

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);

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" 메시지를 포함시켜 중단된 곳에서 계속할 수 있습니다:

{
  "model": "anthropic/claude-sonnet-4.6",
  "messages": [
    { "role": "user", "content": "Name 3 popular programming languages." },
    { "role": "assistant", "content": "1." }
  ]
}

모델은 프리필된 어시스턴트 메시지에서 계속 생성합니다. 이 기법은 다음에 유용합니다:

특정 출력 형식 강제
멀티턴 완성 재개
모델을 특정 응답 구조로 유도

모든 모델이 어시스턴트 프리필을 지원하는 것은 아닙니다. Anthropic Claude와 대부분의 오픈소스 모델은 지원합니다. OpenAI 모델은 제한적으로 지원합니다.

라우팅 내부 동작 원리

model 필드 파싱 → 프로바이더 ID 추출
API key 권한 확인 → 해당 프로바이더가 허용되었는가?
라우터 서비스 호출 → 리전 선택, 풀에서 정상 키 선택
model 필드 재작성 → 프로바이더 접두사 제거
리버스 프록시 → 프로바이더의 API key로 업스트림에 전달
응답 스트리밍 반환 → 사용량 비동기 기록

ARouter는 프로바이더 API key 주입, 헬스 체크, 페일오버를 완전히 투명하게 처리합니다. 애플리케이션은 업스트림 프로바이더의 자격 증명을 절대 볼 수 없습니다.

시작하기

핵심 개념

라우팅

기능

가이드

개인정보

관리

모범 사례

프레임워크 & 통합

공급자 안내

지원

모델 라우팅

`provider/model` 형식

예시

네이티브 SDK 엔드포인트

범용 프로바이더 프록시

자동 라우팅

작동 원리

허용 모델 제한

코드 예시

사용 사례

제한 사항

후보 모델 목록

작동 원리

라우팅 동작

파티션 동작 제어

OpenAI SDK에서 후보 목록 사용

어시스턴트 프리필

라우팅 내부 동작 원리

​provider/model 형식

​예시

​네이티브 SDK 엔드포인트

​범용 프로바이더 프록시

​자동 라우팅

​작동 원리

​허용 모델 제한

​코드 예시

​사용 사례

​제한 사항

​후보 모델 목록

​작동 원리

​라우팅 동작

​파티션 동작 제어

​OpenAI SDK에서 후보 목록 사용

​어시스턴트 프리필

​라우팅 내부 동작 원리

`provider/model` 형식

예시

네이티브 SDK 엔드포인트

범용 프로바이더 프록시

자동 라우팅

작동 원리

허용 모델 제한

코드 예시

사용 사례

제한 사항

후보 모델 목록

작동 원리

라우팅 동작

파티션 동작 제어

OpenAI SDK에서 후보 목록 사용

어시스턴트 프리필

라우팅 내부 동작 원리