
EvoLink Smart Router 사용법: API 설정과 프로덕션 테스트
https://direct.evolink.ai/v1/chat/completions로 OpenAI 호환 Chat Completions 요청을 보내고 model을 evolink/auto로 설정하는 것입니다.response.model에 반환되므로 라우팅 동작을 관찰할 수 있습니다.빠른 참조
| 설정 | 값 | 역할 |
|---|---|---|
| Endpoint | https://direct.evolink.ai/v1/chat/completions | OpenAI 호환 Chat Completions |
| 인증 | Authorization: Bearer $EVOLINK_API_KEY | API 요청 인증 |
| Model ID | evolink/auto | Smart Router 활성화 |
| 요청 형식 | OpenAI 호환 messages 배열 | 일반적인 SDK 패턴 유지 |
| 라우팅 모델 | response.model | 실제 처리 모델 표시 |
| 현재 범위 | 텍스트 및 Agent 워크플로 | 이미지와 비디오는 명시적 ID 사용 |
1. API 키 준비
export EVOLINK_API_KEY="your-api-key"PowerShell:
$env:EVOLINK_API_KEY="your-api-key"개발, Staging, Production에서 서로 다른 키를 사용하면 사용량 분석과 키 Rotation이 쉬워집니다.
2. 첫 요청 보내기
curl --request POST \
--url https://direct.evolink.ai/v1/chat/completions \
--header "Authorization: Bearer $EVOLINK_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "evolink/auto",
"messages": [
{
"role": "user",
"content": "이 문의를 결제, 기술 문제, 계정 접근 중 하나로 분류하세요: 비밀번호를 재설정한 뒤 로그인할 수 없습니다."
}
],
"temperature": 0.2,
"stream": false
}'model입니다.{
"id": "chatcmpl-example",
"object": "chat.completion",
"model": "actual-routed-model",
"choices": [
{
"message": {
"role": "assistant",
"content": "계정 접근"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 26,
"completion_tokens": 4,
"total_tokens": 30
}
}actual-routed-model은 예시입니다. 실제 응답의 model 값을 확인하세요.3. Python 통합
import os
import time
from openai import OpenAI
client = OpenAI(
api_key=os.environ["EVOLINK_API_KEY"],
base_url="https://direct.evolink.ai/v1",
)
started_at = time.perf_counter()
response = client.chat.completions.create(
model="evolink/auto",
messages=[
{
"role": "user",
"content": "이 인시던트 보고서를 요약하고 다음 엔지니어링 작업 두 가지를 제안하세요.",
}
],
temperature=0.2,
)
print("routed_model:", response.model)
print("latency_ms:", round((time.perf_counter() - started_at) * 1000))
print("usage:", response.usage)
print("output:", response.choices[0].message.content)baseURL을 https://direct.evolink.ai/v1, model을 evolink/auto로 설정하면 됩니다.Smart Router 라우팅 과정
- 애플리케이션이
evolink/auto를 사용한 OpenAI 호환 요청을 보냅니다. - 라우터가 작업 유형과 복잡도를 평가합니다.
- Fast, Standard, Reasoning 등의 Profile에 매핑합니다.
- 적합한 후보 모델이 요청을 처리합니다.
- 선택된 모델이
response.model로 반환됩니다.
| Profile | 일반적인 용도 | 예시 |
|---|---|---|
| Fast | 단순하고 대량인 텍스트 작업 | 재작성, 분류, 포맷팅 |
| Standard | 일반 텍스트 처리 | 요약, 추출, 고객지원 분석 |
| Reasoning | 복잡한 분석과 계획 | 다단계 분석, 의사결정 지원 |
| Coding / Agentic Coding | 지원되는 Coding 워크플로 | 코드 리뷰, 디버깅, 리팩터링 계획 |
Profile은 작업 분류이며 영구적인 공개 모델 목록이 아닙니다.
Smart Router와 고정 모델
| 워크로드 | Smart Router | 고정 모델 |
|---|---|---|
| 분류, 추출, 추론이 혼재 | 평가 시작점으로 적합 | 직접 선택 로직 필요 |
| 초기 제품 개발 | 실제 데이터 수집에 유용 | Baseline 확정 후 유용 |
| 엄격한 Benchmark | 모델이 달라질 수 있어 부적합 | 올바른 선택 |
| 결정론적 QA 또는 승인 절차 | 세심한 제어 필요 | 일반적으로 더 안전 |
| 모델 고유 기능 | 보장할 수 없음 | 필수 |
| 이미지 또는 비디오 생성 | 현재 범위 아님 | 명시적 Media Model ID 사용 |
혼합 텍스트에는 라우팅을, 검증되거나 통제된 기능에는 고정 모델을 함께 사용하는 방식이 현실적입니다.
기록해야 할 데이터
| 필드 | 이유 |
|---|---|
| Feature / Workflow 이름 | 서로 다른 트래픽 구분 |
| Request ID | 애플리케이션 로그와 API 조사 연결 |
response.model | 실제 라우팅 모델 확인 |
| Latency | 응답 시간 목표 검증 |
| 입력 및 출력 Token | 사용량과 비용 분석 |
| HTTP Status 및 Retry 횟수 | 신뢰성 문제 확인 |
| 품질 결과 | 작업별 Eval 결과 기록 |
민감한 Prompt나 Response는 조직의 개인정보 및 보존 정책에 맞지 않으면 저장하지 마세요.
프로덕션 전 테스트
- 정상, 모호한 입력, 잘못된 입력을 포함한 대표 테스트셋을 만듭니다.
- 현재 사용하는 고정 모델을 Baseline으로 선택합니다.
- 동일한 Input과 Parameter를
evolink/auto로 실행합니다. - Workflow별 품질, Latency, Token, 오류, 라우팅 모델을 비교합니다.
- 저위험 트래픽부터 시작하고 엄격한 QA에는 고정 모델을 유지합니다.
전체 평균만 보지 말고 작업 유형과 실패 영향에 따라 결과를 확인하세요.
일반적인 API 오류
| Status | 의미 | 권장 대응 |
|---|---|---|
400 | 잘못된 Parameter | JSON, Model ID, 타입 확인 |
401 | 유효하지 않거나 만료된 키 | Bearer token 확인 또는 Rotation |
402 | Quota 부족 | Credit 및 Billing 확인 |
403 | Feature 접근 불가 | Smart Router 권한 확인 |
429 | Rate Limit | 제한된 Retry와 Backoff, Jitter 적용 |
500 / 502 / 503 | 내부 또는 Upstream 오류 | Backoff 후 재시도하고 Fallback 준비 |
명시적인 Timeout을 설정하고 무제한 Retry는 피하세요.
흔한 도입 실수
- Smart Router가 항상 가장 저렴한 모델을 고른다고 가정
- 같은 Prompt가 항상 같은 모델로 간다고 기대
- 이미지 또는 비디오 요청을
evolink/auto에 전송 response.model을 기록하지 않음- 후보 모델 목록을 고정 정보로 공개
FAQ
어떤 Endpoint를 사용해야 하나요?
POST https://direct.evolink.ai/v1/chat/completions를 사용하세요.Smart Router Model ID는 무엇인가요?
model을 evolink/auto로 설정합니다.실제 처리 모델을 확인할 수 있나요?
model 필드를 확인하고 Latency, Token, Workflow Metadata와 함께 기록하세요.Smart Router가 항상 더 저렴한가요?
아닙니다. 실제 비용은 요청, 라우팅 모델, 출력 길이, Retry 및 품질 요구에 따라 달라집니다.
같은 Prompt는 항상 같은 모델로 가나요?
그 동작에 의존하지 마세요. 모델 ID나 재현 가능한 테스트가 필요하면 고정 모델을 사용합니다.
이미지와 비디오에도 사용할 수 있나요?
현재 범위는 지원되는 텍스트 및 Agent 요청입니다. Media 생성에는 명시적 모델 ID를 사용하세요.
Streaming을 사용할 수 있나요?
stream이 있습니다. 프로덕션 계약에 포함하기 전에 계정과 Client에서 동작을 검증하세요.언제 고정 모델로 전환해야 하나요?
Workflow의 우수 모델이 검증됐거나 모델 고유 기능, 엄격한 Regression Test 또는 승인 절차가 필요할 때입니다.
다음 단계
evolink/auto와 고정 모델에 실행하고 품질, Latency, Token, 오류, 반환된 모델을 비교하세요.

