千木DEV

最佳实践

提升 API 使用效率的实用建议，涵盖错误处理、重试策略、成本优化和安全防护。

错误处理

正确处理 API 错误是构建稳定应用的基础。

检查 HTTP 状态码

始终检查响应状态码。2xx 表示成功，4xx 表示客户端错误，5xx 表示服务端错误。

import openai

client = openai.OpenAI(
    base_url="https://api.silvamux.com/v1",
    api_key="sk-your-api-key"
)

try:
    response = client.chat.completions.create(
        model="deepseek-v3.2",
        messages=[{"role": "user", "content": "你好"}]
    )
except openai.AuthenticationError:
    print("API Key 无效，请检查控制台")
except openai.RateLimitError:
    print("请求频率超限，请降低并发或稍后重试")
except openai.APIStatusError as e:
    print(f"API 错误: {e.status_code} - {e.message}")

解析业务错误码

千木（SilvaMux）在响应体中返回结构化错误信息，包含 error.code 字段用于精确定位问题。详见错误码参考。

{
  "error": {
    "type": "insufficient_balance",
    "message": "余额不足，请先充值",
    "code": 40201
  }
}

重试策略

网络请求可能因瞬时故障失败，合理的重试策略可以提高成功率。

指数退避重试

对于 429 (速率限制) 和 5xx (服务端错误)，使用指数退避策略重试。避免对 4xx 错误重试。

import time
import random

def call_with_retry(func, max_retries=3, base_delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except openai.RateLimitError:
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"速率限制，{delay:.1f}s 后重试 (第 {attempt + 1} 次)")
            time.sleep(delay)
        except openai.APIStatusError as e:
            if e.status_code >= 500:
                delay = base_delay * (2 ** attempt)
                print(f"服务端错误 {e.status_code}，{delay:.1f}s 后重试")
                time.sleep(delay)
            else:
                raise  # 4xx 错误不应重试
    raise Exception(f"重试 {max_retries} 次后仍然失败")

response = call_with_retry(lambda: client.chat.completions.create(
    model="deepseek-v3.2",
    messages=[{"role": "user", "content": "你好"}]
))

使用 SDK 内置重试

OpenAI SDK 支持配置自动重试策略，无需手动实现。

client = openai.OpenAI(
    base_url="https://api.silvamux.com/v1",
    api_key="sk-your-api-key",
    max_retries=3,  # 最多重试 3 次
    timeout=30.0,
)

成本优化

合理控制 API 调用成本，避免不必要的资源浪费。

选择合适的模型

不同模型的价格差异显著。简单任务（如分类、提取）使用小模型，复杂任务（如推理、代码生成）使用大模型。

# 简单任务 — 使用轻量模型
response = client.chat.completions.create(
    model="deepseek-v3.2",        # 高性价比通用模型
    messages=[{"role": "user", "content": "将以下文本分类..."}]
)

# 复杂任务 — 使用高级模型
response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",  # 强推理能力
    messages=[{"role": "user", "content": "分析以下代码的安全漏洞..."}]
)

控制 max_tokens

设置合理的 max_tokens 上限，避免生成超出需要的文本。短回答场景建议设置较低的上限。

# 短回答场景
response = client.chat.completions.create(
    model="deepseek-v3.2",
    messages=[{"role": "user", "content": "这个句子是积极还是消极？只回答一个词。"}],
    max_tokens=10,  # 只需要几个 token
)

利用 Prompt 缓存

对于重复的系统提示词和长上下文场景，千木（SilvaMux）支持语义缓存。相似的请求可以直接返回缓存结果，节省 Token 消耗。

流式调用

流式响应可以显著提升用户体验，让用户更快看到内容。

基本流式调用

设置 stream=true 启用 SSE 流式响应。适合交互式对话、实时展示等场景。

stream = client.chat.completions.create(
    model="deepseek-v3.2",
    messages=[{"role": "user", "content": "写一首关于春天的诗"}],
    stream=True,
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

服务端流式转发

在 Web 应用中，使用流式转发将 LLM 响应实时推送到前端，避免长时间等待。

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import openai

app = FastAPI()
client = openai.OpenAI(base_url="https://api.silvamux.com/v1")

@app.post("/chat")
async def chat(request: dict):
    def generate():
        stream = client.chat.completions.create(
            model=request["model"],
            messages=request["messages"],
            stream=True,
        )
        for chunk in stream:
            content = chunk.choices[0].delta.content
            if content:
                yield f"data: {content}\n\n"
        yield "data: [DONE]\n\n"

    return StreamingResponse(generate(), media_type="text/event-stream")

安全建议

保护 API Key 和用户数据安全。

API Key 管理

API Key 通过环境变量或密钥管理服务存储，切勿硬编码在代码中或提交到版本控制。

# 推荐：使用环境变量
import os

client = openai.OpenAI(
    base_url="https://api.silvamux.com/v1",
    api_key=os.environ["SILVAMUX_API_KEY"]
)

设置 Key 权限范围

在控制台创建 API Key 时，可以通过 model_scope 限制 Key 可访问的模型范围，降低密钥泄露的风险。

设置月度额度上限

为每个 API Key 设置 quota_limit（月度消费上限），防止异常使用导致意外费用。

相关文档