接入 Together AI：三个 base_url 别混，限流读响应头而不是抄常量
一、它是什么
Together AI 是托管开放权重模型的推理平台，提供 OpenAI 兼容 API，覆盖文本、图像、视频、代码、语音等模态。平台分三条推理路径：
- Serverless：共享机群，按 token 计费，不用自己开 GPU，适合原型、评测、流量波动。
- Provisioned Throughput：为选定标准模型预留吞吐容量，带 SLA（承诺吞吐与可靠性），适合需要强保证的生产负载。
- Dedicated Model Inference：单模型跑在为你预留的 GPU 上，按硬件分钟计费，适合稳定流量、稳定延迟，或需要部署微调模型。
三条路径共用同一套推理 API（生成与取回模型输出），切换部署模式不改代码，只换 model 参数。Serverless 的 model 形如 model="moonshotai/Kimi-K3"；Dedicated 则把 endpoint 字符串（形如 your-project-slug/endpoint-name）当 model 传。
二、base_url 不止一个
- OpenAI 兼容入口（多数 SDK / 网关）：
https://api.together.xyz/v1 - 官方 Quickstart 新记录的根地址：
https://api.together.ai/v1 - Dedicated model inference 专用：
https://api-inference.together.ai/v1（没有 CLI，只能用 curl 或 SDK 指到该 base URL）
第三方网关 AISIX 文档记载：api_base 已含 /v1，网关会把 /chat/completions 追加到该地址；省略 api_base 时其 Cloud 会回退填 https://api.together.xyz/v1。Dedicated 的 prompt caching 默认开启、无需配置。
三、OpenAI 兼容不等于行为一致
把 OpenAI 客户端指向 Together，要改三处：base_url、api_key（TOGETHER_API_KEY）、model 名。但行为上有边界：
- 官方兼容说明只覆盖 chat / vision / images / embeddings / speech 这些 endpoint，不保证每个参数、流式事件、错误码、工具调用、输出行为完全一致。
- Responses API：Together 没有原生实现，只有 Chat Completions 等价项的字段会被采纳，其余字段被忽略；
/v1/messages/count_tokens仅限 Anthropic 后端模型。 - 网关路由矩阵：
/v1/chat/completions支持缓冲与流式；/v1/completions支持缓冲、不支持流式（要流式就改用 chat/completions）；/v1/images/generations、/v1/rerank在规范化路由中不接受 togetherai provider，得走/passthrough/togetherai/...透传。透传不重写请求体里的别名，无识别载体的缓冲响应记 0 token。
四、限流是动态的
Together 已取消固定的 Build Tier 1–5 标签，限流按组织与模型动态调整，超限返回 429。每次 Serverless 请求的响应头会带当前用量与重置时间——正确做法是读响应头，而不是把旧教程里的 RPM/TPM 常量抄进代码。第三方资料给的 100–500 req/min 只能当粗略参考。
五、成本与选型取舍
| 路径 | 适合场景 | 计费核心 | 主要风险 |
|---|---|---|---|
| Serverless | 原型、低频、流量波动、多模型比较 | 文本按输入/输出 token，其他模态按相应单位 | 动态限流、共享容量、目录变化 |
| Batch | 离线分类、批量生成、无需实时结果 | 选定 Serverless 模型最高 50% 折扣 | 完成时间、任务失败与结果回收 |
| Provisioned Throughput | 标准模型、需要吞吐与 SLA | 合同/预留容量 | 承诺量与真实利用率不匹配 |
| Dedicated Endpoint | 稳定高负载、单租户 GPU、微调模型 | Endpoint 运行期间按 GPU 分钟 | 空闲仍计费、容量规划与运维 |
| Fine-tuning | 固定格式、领域行为、任务适配 | 训练/验证 token，部署另计 | 数据质量、过拟合、基座更新 |
| BYOM | 已有 Hugging Face/S3 权重需托管 | 上传、存储与 Dedicated 运行 | 单节点限制、格式、许可证与依赖 |
不能拿「百万 token 单价」直接和「一张 GPU 每小时」比，要换算成单位成功任务总成本。非实时大批量先看 Batch；利用率与服务目标都明确后再考虑 Dedicated，因为 Dedicated 空闲也计费。
六、调用与排障
鉴权走 Authorization: Bearer $TOGETHER_API_KEY。curl 打到 POST https://api.together.ai/v1/chat/completions，model 必须从实时目录复制，别用过期示例：
curl -X POST https://api.together.ai/v1/chat/completions \
-H "Authorization: Bearer $TOGETHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "<从实时目录复制的 model 名>", "messages": [{"role": "user", "content": "..."}]}'
错误分类：429 → RateLimitError；401 → AuthenticationError；400 → InvalidRequestError。重试要加 jitter，否则所有客户端同时重试会形成惊群：
retry_delay *= 2 + random.random()
生产可把 max_retries 提到 8–10，并加熔断，避免反复失败把配额烧光。
其他几点：
- 超时：OpenAI SDK 默认超时对超大模型偏短，可以设
timeout=60.0，或分别设连接超时与读取超时。 - 流式中断：已收到的内容无法撤回，业务层要自己设计断点续传或重试提示。
- 密钥：只放服务端环境变量或密钥管理，不进浏览器、App 安装包、公开仓库或截图。
- 缓存：应用层可加 Redis / 内存缓存，复用相同输入输出，降低重复调用。
项目与文档地址
- 官网：https://www.together.ai/
- Serverless 推理：https://www.together.ai/serverless-inference
- 推理概览文档：https://docs.together.ai/docs/inference/overview
- Dedicated 请求文档：https://docs.together.ai/docs/dedicated-endpoints/requests
- API Key 管理：https://api.together.ai/settings/api-keys