Mistral API 集成指南

了解基础 URL 变更

您的代码向基础 URL 发送请求并附加密钥。要切换到其他 OpenAI 兼容端点，只需更改这两个值，其余保持不变。路径 /v1/chat/completions 保持不变，因此请求体和响应体保持其结构。

将旧的基础 URL 保存在配置值中，而不是代码中。这样如果生产环境中出现问题，你可以一步切换回来。

SDK 兼容性：OpenAI 与 Mistral 客户端

大多数客户端库接受自定义 base URL。官方 OpenAI SDK、LangChain 和 LlamaIndex 都支持，普通 HTTP 客户端也可以。将 base URL 设置为 https://mistralapibaseurl.com/v1 并传递新密钥。

• 检查 SDK 版本，因为非常旧的版本会忽略基础 URL 设置。
• 检查客户端是否在 Authorization 作为 bearer 令牌。

配置模型 ID

发送模型 id uncensored. 该服务仅提供这一款模型，因此 id 在请求之间不会变化，您无需编写模型选择逻辑。

运行一次请求，使用短提示。回复和使用块表明基础 URL、密钥和模型 id 均正确。

实现流式响应

设置 stream: true 以服务器发送事件的形式接收答案。每个事件携带一小段文本，最后一个事件携带用量数据。

按到达顺序显示文本块，并将完整文本保留在缓冲区中，以便在流结束时存储消息。测量首个 token 的生成时间；该指标反映了聊天对用户的响应速度。

启用函数调用和工具

以您已使用的相同格式传入 tools 数组。模型将返回包含函数名称和 JSON 参数的工具调用。在您的代码中运行该函数，将结果作为工具消息传回，然后读取最终答案。

1. 定义一个包含两个必需参数的工具并单独测试它。
2. 测试需要顺序执行两个工具调用的情况。
3. 在执行任何更改数据的操作之前验证参数。

管理上下文窗口和令牌

上下文窗口为 100,000 个 token。长对话会填满窗口，因此在达到限制之前，请修剪旧轮次或对其进行总结。每次请求最多可返回 16,000 个输出 token，默认值为 2,048，因此请设置 max_tokens 用于你期望的答案。

从每个响应的 usage 字段计算令牌。通过词数估算对于代码和非英语文本往往偏差很大。

处理速率限制和重试

每个密钥允许每分钟 300 次请求和 8 个同时请求。超出限制时，您将收到 429 响应。仅对 429 和 5xx 响应进行重试，采用指数退避策略，并对总等待时间设置上限。

切勿重试 400 或 401 错误，因为相同的请求会以相同的方式再次失败。先修复请求或密钥。

调试常见 API 错误

状态	常见原因	应该做什么
400	JSON 格式错误或未知字段	检查请求体是否符合您发送的格式
401	缺少或错误的密钥	再次复制密钥并检查 Authorization 头
402	额度已用完	充值余额；最低充值金额为 $20
429	达到限流	退避并重试

记录每次失败的状态码和请求 ID，以便快速追踪问题。

从竞争对手 API 迁移

分三个阶段进行迁移：测试环境、少量实时流量，然后完全切换。在中间阶段将两个基础 URL 都保留在配置中，并在相同的提示词下比较答案和延迟。

对比实际使用成本，而非列表价格。将使用字段中的输入和输出 Token 数乘以 $0.15 和 $0.50（每 1M Token），并与您当前的账单进行对比。