迁移 API：常见 LLM 集成错误排查

配置基础 URL 错误

第一个故障点几乎总是基础 URL。当你切换提供商时，必须更新 SDK 连接的端点。错误的 URL 会导致在负载离开你的机器之前就出现 404 或 403 错误。

确保您的客户端指向正确的域名。对于我们的服务，基础 URL 是 https://api.apimigration.com/v1. 此 URL 通过简单地更改 base_url 参数。

• 验证协议（HTTPS 与 HTTP）。
• 检查客户端配置中的尾随斜杠。
• 确认版本路径（/v1) 与您的 API 规范匹配。

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'

忽略上下文窗口限制

您的模型对于 combined prompt 和 completion 有 100,000 token 的硬性限制。如果超出此限制，API 将拒绝请求或根据实现方式静默截断您的历史记录。始终跟踪您的 token 使用情况以避免触及此限制。

此外，每个请求的最大输出为 16,000 个令牌。如果您未设置 max_tokens, 默认值为 2,048 个 token。对于长篇幅生成任务，这一差异非常显著。

• 监控每次请求的总令牌数。
• 设置 max_tokens 明确用于长输出。
• 为超长对话实现滑动窗口逻辑。

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

不正确的流式传输实现

流式响应需要特定的服务器发送事件（SSE）处理。如果你将流视为单个 JSON 对象，你的代码将挂起或崩溃。每个数据块包含部分数据，最后一个数据块包括令牌用量统计信息。

增量读取流。随着每个事件的到达进行处理。这降低了最终用户的感知延迟。不要在处理之前等待整个响应。

• 打开连接并按行读取。
• 解析 data: 行作为 JSON。
• 处理 [DONE] 正确发出信号。

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Tell the story in second person."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

忽略速率限制

我们的 API 每个密钥每分钟允许 300 次请求。如果您的应用程序出现流量峰值，您将收到 429 Too Many Requests 错误。您必须实现指数退避以优雅地处理这些错误。

并发请求也限制为每个密钥同时 8 个。超过此限制可能导致连接池耗尽。密切监控你的并发连接。

• 对 429 错误实现指数退避。
• 将并发连接数限制为 8。
• 高负载时使用断路器模式。

Copyimport OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.apimigration.com/v1", apiKey: process.env.API_KEY });

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);

假设标准 JSON 格式

虽然我们遵循 OpenAI 兼容格式，但假设可能会破坏您的集成。确保您请求 json_object 在 response_format 如果您需要严格的 JSON。否则，模型可能会返回 Markdown 或纯文本。

仔细解析响应。在使用之前验证 JSON 结构。这可以防止下游服务出现运行时错误。

• 设置 response_format 到 {"type": "json_object"}.
• 解析前验证 JSON。
• 优雅处理格式错误的响应。

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'

忽视错误处理

API 会失败。网络超时、服务器错误和无效负载时有发生。您的代码必须在不崩溃的情况下处理这些错误。记录错误详细信息以进行调试。

检查错误代码和消息。对临时错误进行重试。对永久错误快速失败。这种区分可以节省时间和资源。

• 记录错误代码和消息。
• 对 5xx 错误进行带退避的重试。
• 在 4xx 错误时快速失败。

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

支付与密钥轮换问题

我们的 API 通过加密货币使用预付费信用。信用额度永不过期。如果信用额度用完，请求将失败。请监控您的余额，在余额归零前充值。

每个账户有一个活跃密钥。生成新密钥会立即使旧密钥失效。确保您的部署原子性地更新密钥以避免停机。

• 定期监控信用余额。
• 原子轮换密钥。
• 同时更新所有实例。

Copyimport OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.apimigration.com/v1", apiKey: process.env.API_KEY });

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);

最佳实践摘要

迁移成功取决于对细节的关注。验证您的基础 URL。遵守上下文限制。正确处理流式传输。管理速率限制。验证 JSON。处理错误。管理支付和密钥。遵循这些步骤可确保顺利过渡。

上线前请彻底测试您的集成。使用试用余额验证您的设置。这能防止生产环境中昂贵的停机时间。

• 验证基础 URL。
• 遵守上下文限制。
• 正确处理流式传输。
• 管理速率限制。
• 验证 JSON。
• 处理错误。
• 管理支付和密钥。

Copycurl https://api.apimigration.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Run the latest migration script for the user table"}]
  }'