> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yelu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 最佳实践

> 在 Yelu AI API 上构建可靠、安全、可观测且成本可控的生产应用。

生产 AI 集成既需要分布式系统工程，也需要模型输出校验。上线 Yelu 功能前应完成以下检查。

## 发现模型能力

调用 [`GET /v1/models`](/zh/api-reference/models)，并把模型选择保存在配置中。模型可路由不代表支持所有能力；请为视觉、工具、结构化输出和音频建立契约测试。

## 设置边界

* 为每个请求设置连接、读取和总超时。
* 限制输入字节、消息数量、工具 Schema、图片尺寸、音频大小和输出 Token。
* 限制每个用户的并发模型调用和工具循环次数。
* 调用方断开时取消服务端请求。
* 只允许从当前模型目录生成的 Allowlist 中选择模型。

## 选择性重试

仅对 `429` 和临时 `5xx` 使用指数退避、随机抖动与较小总预算；不要原样重试无效或未授权请求。

<CodeGroup>
  ```bash Curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --connect-timeout 10 --max-time 90 \
    --retry 3 --retry-all-errors --retry-delay 1 \
    https://api.yelu.ai/v1/models \
    -H "Authorization: Bearer $YELU_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 90_000);
  try {
    const response = await fetch('https://api.yelu.ai/v1/models', {
      headers: { Authorization: `Bearer ${process.env.YELU_API_KEY}` },
      signal: controller.signal,
    });
    if (!response.ok) throw new Error(await response.text());
    console.log(await response.json());
  } finally {
    clearTimeout(timeout);
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests
  from requests.adapters import HTTPAdapter
  from urllib3.util.retry import Retry

  session = requests.Session()
  session.mount("https://", HTTPAdapter(max_retries=Retry(total=3, backoff_factor=0.5, status_forcelist=[429, 500, 502, 503, 504], allowed_methods=["GET"])))
  response = session.get(
      "https://api.yelu.ai/v1/models",
      headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
      timeout=(10, 30),
  )
  response.raise_for_status()
  print(response.json())
  ```
</CodeGroup>

## 数据与密钥

* Key 只保存在服务端，按环境和工作负载拆分。
* 默认日志应脱敏鉴权、Prompt、工具参数、文件和输出。
* 发送前按数据政策分类并满足保留、地域与合规要求。
* 把模型输出、URL 与工具参数都视为不可信输入。

## 输出可靠性

* 机器消费的数据使用结构化输出，并在本地校验。
* 抽取、分类和工作流控制使用较低随机性。
* 消费结果前检查 Finish Status；`length` 和内容过滤可能产生不完整响应。
* 为 Prompt、Schema、模型变更和回退建立版本化评测。

## 可观测性

记录端点、模型、输入大小、状态码、错误类型、Finish Reason、首 Token 延迟、总延迟、重试次数、用量与结构校验结果；避免记录不必要的内容数据。

## 成本控制

选择通过评测的最小模型，精简历史上下文，限制输出、图片数量/尺寸和音频时长，并使用独立 Key 归因用量。

<Warning>不要静默切换到具有不同安全或数据处理特征的模型。Fallback 是产品与合规决策，不只是可靠性机制。</Warning>