
Qwen3.8 Max 연동 방법: Python, TypeScript, cURL
qwen3.8-max를 사용합니다. 문서 URL은 과거 Preview slug를 유지하므로 프로덕션 ID를 사용하고 Traffic 전 계정에서 Smoke Test를 실행하세요.QwenCloud 출시와 EvoLink 상태
| Surface | ID | 상태 |
|---|---|---|
| QwenCloud | qwen3.8-max | 공식 upstream flagship |
| Token Plan | qwen3.8-max-preview | Preview channel |
| EvoLink | qwen3.8-max | 프로덕션 Route 사용 가능, 문서 URL은 Preview slug 유지 |
첫 요청 전 준비
| 요구 사항 | 준비 | 이유 |
|---|---|---|
| EvoLink API Key | API Key 대시보드에서 생성 | Bearer 인증 |
| Base URL | Text는 https://direct.evolink.ai/v1 | SDK 설정과 Endpoint 분리 |
| Multimodal URL | 이미지·오디오·비디오는 https://api.evolink.ai/v1 | 문서화된 전용 Endpoint |
| 모델 변수 | EvoLink가 표시한 정확한 ID | Preview→GA 변경을 코드 없이 반영 |
| Smoke Test | 짧고 결정적인 Request | Auth, Route, Response, Billing 확인 |
| Fallback | 검증된 EvoLink 모델 | 활성화·용량 변화 시 서비스 유지 |
export EVOLINK_API_KEY="your-evolink-api-key"
export EVOLINK_BASE_URL="https://direct.evolink.ai/v1"
export EVOLINK_QWEN_MODEL="qwen3.8-max-preview"Protocol 결정 트리
기존 OpenAI Chat은 Chat, 도구나 서버 상태가 필요한 새 Agent는 Responses, Anthropic stack은 Messages를 선택합니다.
Existing OpenAI-compatible chat application?
├─ Yes → Chat Completions
└─ No
├─ New agent needs built-in tools or server-linked turns? → Responses
└─ Existing Anthropic Messages stack? → MessagesEVOLINK_QWEN_MODEL을 qwen3.8-max로 설정하고 첫 Response에서 Resolved Model을 확인하세요.Chat, Responses, Messages 선택
| Protocol | Endpoint | 시작하기 좋은 경우 | 차이 |
|---|---|---|---|
| Chat Completions | /v1/chat/completions | 기존 OpenAI 호환 Chat | messages, Thinking은 reasoning_content |
| Responses | /v1/responses | Agent, Built-in Tool, 연결된 Turn | input, previous_response_id, Session Cache |
| Messages | /v1/messages | Anthropic SDK | 최상위 system, max_tokens 필수 |
기존 OpenAI 앱은 Chat, Tool이나 서버 상태는 Responses, Anthropic Block과 Event는 Messages를 선택하세요.
cURL 첫 호출
curl --request POST \
--url "${EVOLINK_BASE_URL}/chat/completions" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--data "{
\"model\": \"${EVOLINK_QWEN_MODEL}\",
\"messages\": [
{
\"role\": \"system\",
\"content\": \"You are a concise software architecture assistant.\"
},
{
\"role\": \"user\",
\"content\": \"Return three checks for a safe API rollout.\"
}
]
}"id, 해석된 model, 최소 한 개의 choices, usage가 있어야 합니다. 활성화 테스트에서 반환 모델을 기록하세요.OpenAI SDK로 Python 연동
pip install openaiimport os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["EVOLINK_API_KEY"],
base_url=os.getenv("EVOLINK_BASE_URL", "https://direct.evolink.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["EVOLINK_QWEN_MODEL"],
messages=[
{
"role": "system",
"content": "You are a concise software architecture assistant.",
},
{
"role": "user",
"content": "Return three checks for a safe API rollout.",
},
],
)
print(response.choices[0].message.content)
print(response.model)연동 경계는 API Key, Base URL, Model ID뿐입니다. Prompt나 Business Logic을 바꾸기 전에 설정으로 출력과 운영 특성을 비교하세요.
TypeScript 연동
npm install openaiimport OpenAI from "openai";
const apiKey = process.env.EVOLINK_API_KEY;
const model = process.env.EVOLINK_QWEN_MODEL;
if (!apiKey || !model) {
throw new Error("EVOLINK_API_KEY and EVOLINK_QWEN_MODEL are required");
}
const client = new OpenAI({
apiKey,
baseURL: process.env.EVOLINK_BASE_URL ?? "https://direct.evolink.ai/v1",
});
const response = await client.chat.completions.create({
model,
messages: [
{
role: "system",
content: "You are a concise software architecture assistant.",
},
{
role: "user",
content: "Return three checks for a safe API rollout.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.model);Streaming에서 Thinking과 최종 내용 분리
reasoning_content와 content를 분리 저장하세요.import os
from openai import OpenAI
model = os.environ.get("EVOLINK_QWEN_MODEL")
if not model:
raise RuntimeError("EVOLINK_QWEN_MODEL is required")
client = OpenAI(
api_key=os.environ["EVOLINK_API_KEY"],
base_url=os.getenv("EVOLINK_BASE_URL", "https://direct.evolink.ai/v1"),
)
stream = client.chat.completions.create(
model=model,
messages=[
{"role": "user", "content": "Review this rollout plan for failure modes."}
],
stream=True,
extra_body={"enable_thinking": True},
)
for chunk in stream:
delta = chunk.choices[0].delta
reasoning = getattr(delta, "reasoning_content", None)
if reasoning:
print(reasoning, end="", flush=True)
if delta.content:
print(delta.content, end="", flush=True)EVOLINK_QWEN_MODEL을 검증하세요. 조용한 Fallback은 Rollout과 Rollback 감사를 어렵게 합니다.Tool과 Multi-turn 상태를 위한 Responses
messages 대신 input을 씁니다. EvoLink는 previous_response_id와 x-dashscope-session-cache: enable도 문서화합니다.curl --request POST \
--url "${EVOLINK_BASE_URL}/responses" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--header "x-dashscope-session-cache: enable" \
--data "{
\"model\": \"${EVOLINK_QWEN_MODEL}\",
\"input\": \"List the production checks for a model-route canary.\"
}"Responses 후속 턴과 Session Cache
previous_response_id로 사용합니다. Header만으로 hit가 증명되지 않으므로 usage를 확인하세요.curl --request POST \
--url "${EVOLINK_BASE_URL}/responses" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--header "x-dashscope-session-cache: enable" \
--data "{
\"model\": \"${EVOLINK_QWEN_MODEL}\",
\"previous_response_id\": \"resp_FROM_FIRST_CALL\",
\"input\": \"Turn those checks into a five-step canary plan.\"
}"id를 저장하세요. 현재 문서는 7일 유효하다고 설명하므로 장기 Workflow 전에 다시 확인해야 합니다.Anthropic 호환 Messages
messages 밖에 두며 max_tokens가 필수입니다.curl --request POST \
--url "${EVOLINK_BASE_URL}/messages" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--data "{
\"model\": \"${EVOLINK_QWEN_MODEL}\",
\"max_tokens\": 1024,
\"system\": \"You are a concise software architecture assistant.\",
\"messages\": [
{
\"role\": \"user\",
\"content\": \"Return three checks for a safe API rollout.\"
}
]
}"도구 검증, 제한 재시도 및 Fallback
도구 인자는 신뢰할 수 없는 입력입니다. 부작용 전에 이름, Schema, 권한, 환경을 검증하세요.
import { z } from "zod";
const createCanarySchema = z.object({
workload: z.string().min(1).max(80),
trafficPercent: z.number().min(0.1).max(10),
});
function validateToolCall(name: string, rawArguments: string) {
if (name !== "create_canary") {
throw new Error(`Blocked unknown tool: ${name}`);
}
return createCanarySchema.parse(JSON.parse(rawArguments));
}Timeout, 연결 오류, 429, 일시적 5xx만 제한적으로 재시도하고 400/401/402는 그대로 반복하지 마세요.
import os
import random
import time
from openai import APIConnectionError, APIStatusError, APITimeoutError, OpenAI
client = OpenAI(
api_key=os.environ["EVOLINK_API_KEY"],
base_url=os.getenv("EVOLINK_BASE_URL", "https://direct.evolink.ai/v1"),
)
def complete_with_fallback(messages):
models = [
os.environ["EVOLINK_QWEN_MODEL"],
os.environ["EVOLINK_FALLBACK_MODEL"],
]
for model in models:
for attempt in range(3):
try:
return client.chat.completions.create(
model=model,
messages=messages,
timeout=60,
)
except APIStatusError as error:
if error.status_code != 429 and error.status_code < 500:
raise
except (APIConnectionError, APITimeoutError):
pass
time.sleep((2 ** attempt) + random.random())
raise RuntimeError("Primary and fallback routes failed")프로덕션 검증 원장
| 기능 | Route 상태 | 계정에서 기록할 증거 |
|---|---|---|
| Chat / Responses / Messages | 사용 가능, 검증 필요 | ID, model, HTTP, stop, usage |
| Streaming / Thinking | 사용 가능, 검증 필요 | 첫 event, 최종 event, reasoning, content |
| Tools / Cache / Multimodal | 대상 Endpoint에서 검증 | 인자, 후속 호출, cache usage, media 형식 |
system, Content Block, Cache Field, Anthropic Streaming Event를 유지하세요.
Thinking, Streaming, Tools, Cache를 단계적으로 활성화
| 기능 | Chat | Responses | Messages | 프로덕션 확인 |
|---|---|---|---|---|
| Thinking | enable_thinking, reasoning_content | reasoning.effort | thinking Block | 품질, 지연, Token |
| Streaming | stream: true, SSE | Responses Event | Anthropic Event | 연결 종료, 부분 출력 |
| Tools | tools 함수 | Built-in·Custom Tool | Tool Block | Side Effect 전 인자 검증 |
| Cache | cache_control | Session Cache Header | cache_control Block | usage 확인 |
| Multimodal | https://api.evolink.ai/v1 | Multimodal URL | 지원 Image Block | 형식과 크기 실경로 테스트 |
QwenCloud 가격이나 Cache 할인을 EvoLink 비용으로 복사하지 마세요. EvoLink 제품 페이지의 Live 가격을 사용합니다.
문제 해결
| 증상 | 원인 | 조치 |
|---|---|---|
400 | 형식 또는 필수 Field 오류 | 최소 예제로 축소 |
401 | Token 오류 | Key와 Header 확인 |
402 | Credit 부족 | 잔액 확인 |
404 | Route, ID, Endpoint 오류 | 정확한 ID와 Path 확인 |
429 | Rate Limit | Jitter 포함 지수 Backoff, 동시성 축소 |
5xx | 일시적 오류 | 제한된 Retry 후 Fallback |
| Thinking에서 빈 Text | 잘못된 Field 읽기 | Reasoning과 최종 Output 확인 |
400, 401, 402는 원인을 고치지 않고 재시도하지 마세요. 429와 일시적 5xx의 Retry 횟수를 제한하세요.
프로덕션 Rollout 체크리스트
- 정확한 ID를
EVOLINK_QWEN_MODEL에 설정합니다. - 짧은 Non-streaming Call로 모델과 usage를 저장합니다.
- Streaming, Tools, Thinking, Cache, Multimodal을 따로 테스트합니다.
- 대표 작업 20–50개를 현재 Baseline과 비교합니다.
- 성공률, 수용 지연, Retry, Token, 수정 시간을 측정합니다.
- Shadow Traffic 후 작은 Canary로 진행합니다.
- 같은 Gateway에 검증된 Fallback을 유지합니다.
- Error, Latency, Cost, Quality가 Guardrail을 넘으면 Rollback합니다.
첫 프로덕션 호출 전에 라우트 확인하기
출시 소식만 보고 바로 가입하지 마세요. 다섯 항목을 먼저 확인하고 워크로드에 맞을 때만 API 키를 만드세요.
- 01
출시됐나요?
예. Qwen3.8 Max가 정식 모델이며 Preview는 과거 채널 정보입니다.
- 02
사용할 수 있나요?
EvoLink에서 사용할 수 있습니다. 제품 페이지에서 활성 라우트와 모델 ID를 확인하세요.
- 03
내 작업에 맞나요?
긴 컨텍스트 추론, 대규모 저장소, 도구 중심 Agent에 적합하며 단순 작업은 더 작은 라우트에 유지합니다.
- 04
가격은 얼마인가요?
제품 페이지의 실시간 가격을 확인하고 upstream 또는 Preview 요금을 재사용하지 마세요.
- 05
어떻게 호출하나요?
Chat Completions, Responses, Messages 중 하나를 선택하고 연동 가이드와 파라미터 문서를 확인하세요.
다섯 항목을 모두 확인했나요? API 키 만들기.
자주 묻는 질문
EvoLink에서 이미 호출할 수 있나요?
qwen3.8-max를 사용하고 계정 표시와 Smoke Test 성공을 확인한 뒤 프로덕션 Traffic을 시작하세요.어떤 Model ID를 사용하나요?
qwen3.8-max, 현재 EvoLink 문서는 qwen3.8-max-preview이므로 설정으로 관리하세요.어떤 Base URL을 사용하나요?
https://direct.evolink.ai/v1, 이미지·오디오·비디오는 https://api.evolink.ai/v1입니다.Chat과 Responses 중 무엇을 선택하나요?
기존 OpenAI 앱은 Chat, 연결된 Turn·Built-in Tool·Responses Event는 Responses입니다.
Anthropic SDK를 사용할 수 있나요?
/v1/messages를 사용하고 system, max_tokens, Block, Event를 유지하세요.가격이 포함되어 있나요?
아닙니다. 가격은 모델 페이지가 담당해 오래된 중복 정보와 키워드 카니발리제이션을 막습니다.
Rate Limit은 어떻게 처리하나요?
동시성을 제한하고 429에 Jitter Backoff, Retry 상한, Fallback을 적용합니다.
프로덕션 전에 무엇을 테스트하나요?
Auth, Model Resolution, Parsing, Streaming, Tools, Thinking, Cache, Multimodal, Timeout, Retry, Billing, Fallback, Shadow, Canary입니다.


