EvoLink Smart Router 使用教程：API 接入与生产验证

Smart Router 快速参考

1. 创建并保存 API Key

在 EvoLink 控制台创建 API Key，然后通过环境变量保存，不要硬编码在应用代码中：

export EVOLINK_API_KEY="your-api-key"

PowerShell：

$env:EVOLINK_API_KEY="your-api-key"

建议为本地开发、测试环境和生产环境使用不同的 Key，以便分别分析用量和执行密钥轮换。

2. 发送第一个 Smart Router 请求

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
  }'

{
  "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
  }
}

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)

如果 Prompt 或返回内容可能包含密钥、个人信息或客户数据，不要直接写入日志。日志应遵循团队自己的隐私和数据保留要求。

Smart Router 如何完成路由

对于支持的文本请求，路由过程可以概括为五步：

1. 应用发送使用 evolink/auto 的 OpenAI 兼容请求。
2. 路由器分析任务类型和复杂度。
3. 请求被映射到 Fast、Standard 或 Reasoning 等路由配置。
4. 合适的候选模型处理请求。
5. 实际选择的模型通过 response.model 返回。

这些配置代表任务类别，不是永久不变的公开模型列表。不要在业务代码中依赖某个固定候选池。

Smart Router 与固定模型怎么选

实际生产架构通常同时保留两条路径：

• 混合或仍在变化的文本工作负载使用 evolink/auto
• 已完成评估、依赖模型能力或需要严格控制的功能使用固定模型 ID

每次路由请求应该记录什么

质量结果可以是确定性校验、人工标签、测试用例结果或其他适合该任务的评估方式。不要用一个通用分数覆盖所有工作流。

生产部署前如何验证

第一步：准备有代表性的测试集

使用真实业务样本，覆盖常规请求、模糊输入、长 Prompt、错误格式，以及输出错误会造成明显风险的场景。

第二步：选择固定模型 Baseline

使用应用当前调用的固定模型作为对照。Prompt、参数和评估规则必须保持一致。

第三步：运行 Smart Router

第四步：按工作流而不是只看平均值

Router 的整体平均结果可能很好，但仍可能不适合某个高风险功能。应按任务类型、客户层级、延迟要求和失败影响拆分分析。

第五步：先灰度低风险流量

先选择可以复核或重试的工作流。严格 QA、敏感操作以及依赖特定模型能力的功能继续使用固定模型。

常见 API 错误及处理方式

客户端应设置明确的 Timeout。不要无限重试，否则会放大延迟、重复任务和成本。

常见接入误区

• 认为 Smart Router 一定选择最便宜的模型
• 认为同一个 Prompt 永远命中同一个模型
• 将图像或视频生成请求发送给 evolink/auto
• 没有记录 response.model
• 对外发布一个固定不变的候选模型列表

FAQ

EvoLink Smart Router 使用哪个 Endpoint？

启用 Smart Router 的 Model ID 是什么？

如何知道请求最终使用了哪个模型？

Smart Router 一定比固定模型便宜吗？

不一定。实际成本取决于请求内容、路由模型、输出长度、重试次数和质量要求。

同一个 Prompt 会一直使用同一个模型吗？

不要依赖这种行为。如果业务要求明确的模型身份或可复现测试，应使用固定模型 ID。

Smart Router 可以路由图像和视频生成吗？

当前产品范围是支持的文本和 Agent 请求。图像和视频生成应使用明确的模型 ID。

支持 Streaming 吗？

什么时候应该改用固定模型？

当某个工作流已经有明确的最佳模型、依赖模型特有能力，或者需要严格的回归测试和审批流程时。

下一步