
如何接入 Qwen3.8 Max:Python、TypeScript 与 cURL
qwen3.8-max,支持 Chat Completions、Responses 与 Messages。当前文档 URL 仍保留历史 Preview slug,因此代码应使用产品页公布的正式 ID,并在发送生产流量前完成一次账户级真实冒烟测试。QwenCloud 发布与 EvoLink 路由状态
| 层级 | 模型 ID | 2026 年 8 月 3 日状态 |
|---|---|---|
| QwenCloud 正式目录 | qwen3.8-max | 上游正式旗舰;1M、Thinking、Function Calling、内置工具、Structured Output |
| Qwen Token Plan | qwen3.8-max-preview | Preview 评测通道,不能确定 EvoLink ID |
| EvoLink 正式路由 | qwen3.8-max | 已可用;Chat / Responses / Messages 共用正式 ID,文档 URL 保留 Preview 历史 slug |
首次请求前需要准备什么
| 要求 | 需要准备 | 原因 |
|---|---|---|
| EvoLink API Key | 在 API Key 控制台创建密钥 | 所有请求都使用 Bearer 认证 |
| Base URL | 文本与长连接使用 https://direct.evolink.ai/v1 | 将 SDK 配置与具体端点路径分离 |
| 多模态 Base URL | 图片、音频或视频输入使用 https://api.evolink.ai/v1 | EvoLink 将其记录为主要多模态端点 |
| 模型环境变量 | 设置为 qwen3.8-max | 让 Canary 与回滚保持可审计 |
| 冒烟测试 Prompt | 一条简短且确定的请求 | 在扩大测试前验证认证、路由、响应结构和计费 |
| 回退模型 | 一个已通过 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"用决策树选协议
现有 OpenAI Chat 应用选 Chat Completions;新 Agent 需要内置工具或服务端多轮状态选 Responses;已有 Anthropic 栈选 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? → Messagesqwen3.8-max 与最终 EvoLink ID 必然相同。选择 Chat、Responses 还是 Messages
EvoLink 提供三种兼容请求接口。应根据应用架构选择一种,而不是让同一工作流同时调用三种。
| 协议 | 端点 | 最适合 | 重要差异 |
|---|---|---|---|
| Chat Completions | /v1/chat/completions | 已有 OpenAI 兼容聊天应用 | 使用 messages;思考内容通过 reasoning_content 返回 |
| Responses | /v1/responses | 新 Agent、内置工具与服务端关联会话 | 使用 input、previous_response_id 和可选会话缓存 |
| Messages | /v1/messages | Anthropic SDK 与 Messages 兼容 Agent | 使用顶层 system 字段且必须提供 max_tokens |
已有 OpenAI Chat Completions 数据结构时优先选择 Chat。需要内置工具或服务端多轮状态时使用 Responses。应用已经保存 Anthropic 风格内容块与事件时选择 Messages。
用 cURL 完成首次调用
以下请求遵循 EvoLink 的 Chat Completions 契约:
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 条目和 Token 用量。启用测试时记录返回的模型字符串,可作为网关是否按预期解析别名的证据。使用 OpenAI SDK 接入 Python
安装当前 OpenAI Python SDK,并将它指向 EvoLink:
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 和模型 ID。这也是最安全的迁移方式:先改配置,再比较输出和运行表现,然后才调整 Prompt 或业务逻辑。
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);分开解析流式 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 存在,而不是静默回退到另一个模型。明确配置才能让上线与回滚可审计。用 Responses API 实现工具和多轮状态
input 而不是 messages。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 只表示请求 Session Cache,不代表已经命中;必须记录 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。EvoLink 当前文档称该 ID 七天内有效;将它用于持久工作流前请再次确认契约。面向 Anthropic 兼容应用的 Messages API
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
模型生成的工具参数属于不可信输入。执行写操作前校验名称、JSON 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));
}只对超时、连接失败、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")路由上线验证台账
| 能力 | 当前状态 | 上线后记录 |
|---|---|---|
| Chat / Responses / Messages | 待路由启用 | ID、resolved model、HTTP、finish/stop、usage |
| Streaming / Thinking | 待路由启用 | 首事件延迟、最终事件、推理与最终内容 |
| Tools / Cache / Multimodal | 待路由启用 | 参数、续调、cache usage、媒体格式与大小 |
system 项移进 Messages 数组来机械转换 Chat 请求。应保留该协议的顶层 system、内容块格式、缓存字段和流式事件类型。
有计划地启用思考、流式输出、工具和缓存
这些功能会改变响应解析、延迟、Token 用量或状态,应逐项启用。
| 功能 | Chat Completions | Responses | Messages | 生产检查 |
|---|---|---|---|---|
| 思考 | enable_thinking;解析 reasoning_content | reasoning.effort | thinking 内容块 | 衡量可接受结果质量、延迟和输出 Token |
| 流式输出 | stream: true;OpenAI 风格 SSE 分片 | Responses 事件 | Anthropic 风格消息事件 | 处理断连和部分输出 |
| 工具 | tools 中的函数定义 | 内置与自定义函数工具 | Anthropic 兼容工具块 | 执行副作用前验证参数 |
| 缓存 | 支持内容上的显式 cache_control | 会话缓存请求头与文档化缓存行为 | cache_control 内容块 | 检查 usage 字段,不要假设命中 |
| 多模态输入 | 使用 https://api.evolink.ai/v1 | 使用多模态 Base URL | 使用支持的图片块 | 在真实路由验证目标媒体格式与大小 |
不要把 QwenCloud 的价格或缓存折扣复制到 EvoLink 成本估算中。上游模型、Token Plan 与 EvoLink 网关属于不同商业渠道,应使用 EvoLink 产品页的实时价格。
排查首次接入问题
| 现象 | 可能原因 | 安全处理方式 |
|---|---|---|
400 invalid_request_error | 协议结构错误、不支持的字段或缺少必填值 | 缩减为所选端点的最小示例 |
401 authentication_error | Bearer Token 缺失、过期或格式错误 | 创建或轮换 EvoLink Key 并确认请求头 |
402 insufficient_quota | 账户余额不足 | 重试前检查账户余额 |
404 或 model not found | 路由未启用、ID 已变化或端点错误 | 从 EvoLink 复制准确模型 ID 并检查协议路径 |
429 rate_limit_error | 请求或 Token 速率超限 | 使用带抖动的指数退避并降低并发 |
500 或瞬时网关错误 | 上游或网关故障 | 有限重试,之后使用已配置回退 |
| 开启思考后最终文本为空 | 客户端只读取了一个响应字段 | 检查所选协议的 reasoning 与最终内容字段 |
不要盲目重试 400、401 或 402;应先修正请求、凭证或账户状态。429 和瞬时 5xx 只能有限重试,否则 Agent 循环会放大成本和负载。
生产上线检查清单
- 将准确的 EvoLink 模型 ID 写入
EVOLINK_QWEN_MODEL。 - 运行一次简短、非流式文本请求,保存解析后的模型和用量。
- 分别测试流式输出、工具、思考、缓存和多模态输入。
- 对当前生产基线重放 20–50 个代表任务。
- 测量首轮成功率、可接受结果延迟、重试次数、输出 Token 与人工修正时间。
- 从影子流量开始,再为单个工作负载开启小比例 Canary。
- 在同一个 EvoLink 网关后保留已验证的回退模型。
- 当错误率、延迟、每个可接受结果成本或任务质量越过护栏时回滚。
首次生产调用前,先核验路由
不要因为一条发布消息就直接注册。先完成以下判断;只有路由确实适合你的工作负载时,再创建 API Key。
- 01
发布了吗?
已发布。Qwen3.8 Max 是正式模型,Preview 仅作为历史渠道背景保留。
- 02
能用吗?
已在 EvoLink 上线。请在产品页确认实时路由与模型 ID。
- 03
适合我吗?
更适合长上下文推理、大型代码仓库和多工具 Agent;轻量任务应继续使用更小的路由。
- 04
多少钱?
以产品页实时价格模块为准,不要套用上游价格或 Preview 套餐价格。
- 05
怎么调用?
从 Chat Completions、Responses 或 Messages 中选择协议,再查看接入指南和参数文档。
五项判断都完成了? 创建 API Key.
常见问题
千问3.8 Max 现在可以通过 EvoLink 调用吗?
截至 2026 年 8 月 3 日,EvoLink 正在完成路由启用。请求契约已经发布,但应等模型出现在账户中且冒烟测试成功后再发送生产流量。
应该使用哪个模型 ID?
qwen3.8-max,当前 EvoLink 草案文档使用 qwen3.8-max-preview。请把它放在配置中,以便无需发布代码即可修改。应该使用哪个 Base URL?
https://direct.evolink.ai/v1。请求包含图片、音频或视频时,EvoLink 将 https://api.evolink.ai/v1 记录为主要端点。新应用应该使用 Chat 还是 Responses?
已有 OpenAI 兼容应用最适合从 Chat 开始。需要服务端关联多轮、内置工具或 Responses 事件流时,更适合选择 Responses。
可以使用 Anthropic SDK 吗?
/v1/messages 契约。保留顶层 system、必填 max_tokens、内容块以及 Anthropic 风格流式事件。本教程包含千问3.8 Max 价格吗?
不包含。价格归千问3.8 Max 产品页和 EvoLink 实时价格页面所有,避免教程产生过期重复内容和关键词重叠。
应该如何处理限流?
限制并发,为 429 响应增加带抖动的指数退避,限制重试次数并保留回退路由。不要原样重试无效请求或认证错误。
上生产前应该测试什么?
验证认证、模型解析、响应解析、流式输出、工具、思考、缓存、多模态输入、超时、重试上限、计费可见性和回退,然后运行面向真实工作负载的影子与 Canary 评估。


