together-python · 协议与工具集成

Together.ai Logo 图1：Together.ai 官方品牌标识

当你的代码需要调用最强开源大模型——这个官方SDK让一切变得简单

2023年，一家名为 Together.ai 的创业公司做了一件让整个AI开源社区振奋的事：他们搭建了一个推理平台，聚合了 Llama、Mistral、DeepSeek 等数十个顶级开源大模型，让开发者可以通过统一的 API 调用这些模型，而不必自己折腾 GPU、配置推理服务、自建模型服务。对于无数没有高端显卡、又不满足于闭源 API 限制的开发者来说，这就像是打开了一扇通往AI能力宝库的大门。而 together 这个 Python SDK，就是通往这扇门的官方钥匙。

一、项目起源：开源模型聚合平台的官方客户端

Together.ai 成立于2023年，由 UC Berkeley 教授 Ion Stoica 联合创立，目标是成为"开源AI模型的AWS"。平台托管了数百个开源模型，包括 Meta 的 Llama 系列、Mistral AI 的系列模型、Qwen、DeepSeek 系列等。与 OpenAI API 最大的不同在于：Together.ai 上的模型可以微调（Fine-tuning），支持全量微调和 LoRA 微调，且提供公开的模型排行榜（Together Chess Leaderboard），让开发者可以横向对比不同模型的表现。

togethercomputer/together 仓库正是 Together.ai 官方发布的 Python 客户端库，采用 Apache-2.0 开源许可，支持 Python 3.10+，通过 pip 一键安装即可使用。目前 V1 版本已标记为 deprecated，官方已迁移至 together-py（SDK v2）继续开发，但 V1 仍处于维护状态。

二、核心技术架构：资源模块化 + 同步/异步双通道

这个 SDK 的架构设计非常清晰——采用模块化资源模式（Module Resource Pattern）。核心入口是 Together 类，它在初始化时注入一个 TogetherClient 对象（包含 API Key、Base URL、超时配置），然后依次挂载各类资源模块：

client = Together(api_key="...")
client.chat.completions.create(model="meta-llama/Llama-4-Scout-17B-16E-Instruct", messages=[...])
client.embeddings.create(model="BAAI/bge-en-erick", input="Hello world")
client.files.upload(file=open("data.jsonl", "rb"))
client.fine_tuning.create(training_file="file-xxx", model="meta-llama/Llama-3.2-3B-Instruct")

所有 API 调用最终都通过底层的 APIRequestor 发送 HTTP 请求，使用 requests 库处理同步请求、aiohttp 处理异步请求。在 src/together/resources/ 目录下，每个功能模块对应一个独立子目录：

功能模块	说明	核心文件
chat/completions	Chat 聊天补全（支持多模态图文）	completions.py
completions	纯文本补全	completions.py
embeddings	向量化嵌入	embeddings.py
files	文件上传管理（支持多段并发上传）	files.py
fine_tuning	模型微调（全量+LoRA）	finetune.py
rerank	文档重排序	rerank.py
audio	语音合成/翻译/转录	speech.py, transcriptions.py
images	图片生成	images.py
videos	视频生成	videos.py
batches	批量推理任务	batch.py
code_interpreter	代码执行沙箱	code_interpreter.py
evaluation	模型评估	evaluation.py

数据类型定义全部采用 Pydantic v2，在 src/together/types/ 目录下提供完整的请求/响应模型，包括流式输出（ChatCompletionChunk）、工具调用（tools）、日志概率（logprobs）等复杂结构，确保类型安全和 IDE 自动补全。

三、深度功能解析：不止于 API 封装

3.1 多模态聊天：一张图片，一段文字，统一接口

Together SDK 的 Chat Completions 接口原生支持多模态消息。传入一个包含 type: "image_url" 的 content item，即可让模型处理图片。代码示例：

response = client.chat.completions.create(
    model="meta-llama/Llama-3.2-11B-Vision-Instruct-Turbo",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "这张图里有什么？"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
    ]}]
)

这套接口设计与 OpenAI Chat Completions API 完全对齐，开发者从 OpenAI SDK 迁移到 Together SDK 成本极低，只需更换 base URL 和 API key 即可。

3.2 批量推理（Batches）：成本降低50%的秘密

Together API 提供 Batch API，允许用户提交一个包含多个独立请求的 JSONL 文件，平台在 24 小时内异步处理，费用比同步 API 低 50%。SDK 的 client.batches 模块完整封装了这一能力，支持创建、查询、取消批量任务。适合数据标注、批量翻译、内容生成等离线批处理场景。

3.3 模型微调（Fine-tuning）：在开源模型上训练自己的AI

这是 Together.ai 平台区别于大多数推理 API 的核心能力。SDK 支持：

全量微调（Full Fine-tuning）：更新模型全部参数，效果好但成本高、耗时长
LoRA 微调：仅训练低秩适配器，显存需求低至单卡 A100 80GB，适合大多数团队
多数据集格式支持：支持 general（纯文本）、conversation（对话）、instruction（指令）、preference（偏好）四种数据集格式
S3 兼容文件上传：支持分段并发上传（最大支持 50GB 文件），并自动验证 Parquet 文件列结构

3.4 代码解释器（Code Interpreter）：让AI真正执行代码

Together 平台提供的 Code Interpreter 功能，允许模型动态生成并执行 Python 代码、访问文件系统、运行 shell 命令。这相当于给大模型配备了一个完整的 Python 运行时环境，可以进行数据分析、图表绘制、数学计算等实际操作。SDK 的 client.code_interpreter 模块封装了提交任务、查询结果、下载输出文件等完整流程。

3.5 CLI 工具：命令行也能玩转AI

SDK 还内置了一个 Typer CLI，提供交互式命令行界面：

together chat completions.create --model meta-llama/Llama-4-Scout-17B-16E-Instruct
together files list
together fine_tuning retrieve --fine-tune-id ft-xxxx
together models list

CLI 对开发者来说非常实用，特别是在调试 API、查看模型列表、快速测试模型输出等场景。

四、技术质量评估

维度	评分	说明
代码质量	★★★★☆	遵循 PEP8 + Black 格式化，Pydantic v2 强类型约束，Mypy 静态检查
测试覆盖	★★★★☆	pytest 完整测试套件，包含 integration 和 unit 目录，pre-commit 检查
文档质量	★★★★★	官方文档详尽，README 包含所有功能的使用示例，配套官方迁移指南
类型安全	★★★★★	全程 Pydantic v2，所有请求/响应严格建模，IDE 自动补全体验优秀
兼容性	★★★★☆	Python 3.10+，同步/异步双通道，OpenAI SDK 接口对齐，迁移成本低

五、上手门槛分析

维度	说明
编程要求	Python 3.10+ 基础即可，无需深度学习知识
硬件要求	零 GPU 要求，纯客户端 SDK，所有计算在 Together 云端完成
API Key	需注册 Together.ai 账号（api.together.xyz），有免费额度
安装方式	`pip install together`，无其他依赖冲突
费用	调用按 token 计费，Batch API 半价，免费额度可申请

六、局限与注意事项

1. V1 版本已过时：目前 SDK V1 已标记 deprecated，官方新功能全部在 together-py（V2）。新项目应直接使用 V2。

2. 中国大陆访问限制：Together.ai 平台服务器位于境外，国内访问需要稳定的国际网络连接，部分区域可能存在延迟。

3. 非本地部署：这是一个调用远程 API 的客户端库，不提供任何模型的本地部署能力。如需本地离线运行开源模型，应考虑 llama.cpp、Ollama 等本地推理框架。

4. 模型可用性依赖平台：SDK 的能力上限受限于 Together.ai 平台支持的模型，部分前沿模型可能需要申请或等待排期。

七、行业意义与趋势

Together.ai 的出现标志着开源大模型"平台化"趋势的成熟。在此之前，开发者使用开源模型面临三重门槛：找到可用权重、解决推理算力、编写推理服务代码。Together.ai 的聚合平台 + SDK 生态将这三重门槛降到了最低——一行 pip install together 就能调用全球最强的开源模型。

这种"模型即服务"（Model-as-a-Service）的模式，正在与 Hugging Face（模型托管）、vLLM（推理优化）、Ollama（本地推理）形成互补的生态格局。Together 的 SDK 处于这个生态的最前端——它是开发者接触 Together 平台的第一入口，也是整个 Together 开发者体验的核心组成部分。

对于 AI 应用开发者而言，掌握 Together SDK 意味着拥有了一个快速验证创意、对比模型能力、低成本实验微调效果的强大工具链。而对于 AI 爱好者，这个 SDK 更是降低了接触顶级开源模型的门槛——无需显卡，只需一个 API key，就能用上 Llama、DeepSeek 等顶级模型。

Together.ai Logo 图1：Together.ai 官方品牌标识

当你的代码需要调用最强开源大模型——这个官方SDK让一切变得简单

一、项目起源：开源模型聚合平台的官方客户端

二、核心技术架构：资源模块化 + 同步/异步双通道

client = Together(api_key="...")
client.chat.completions.create(model="meta-llama/Llama-4-Scout-17B-16E-Instruct", messages=[...])
client.embeddings.create(model="BAAI/bge-en-erick", input="Hello world")
client.files.upload(file=open("data.jsonl", "rb"))
client.fine_tuning.create(training_file="file-xxx", model="meta-llama/Llama-3.2-3B-Instruct")

功能模块	说明	核心文件
chat/completions	Chat 聊天补全（支持多模态图文）	completions.py
completions	纯文本补全	completions.py
embeddings	向量化嵌入	embeddings.py
files	文件上传管理（支持多段并发上传）	files.py
fine_tuning	模型微调（全量+LoRA）	finetune.py
rerank	文档重排序	rerank.py
audio	语音合成/翻译/转录	speech.py, transcriptions.py
images	图片生成	images.py
videos	视频生成	videos.py
batches	批量推理任务	batch.py
code_interpreter	代码执行沙箱	code_interpreter.py
evaluation	模型评估	evaluation.py

三、深度功能解析：不止于 API 封装

3.1 多模态聊天：一张图片，一段文字，统一接口

Together SDK 的 Chat Completions 接口原生支持多模态消息。传入一个包含 type: "image_url" 的 content item，即可让模型处理图片。代码示例：

response = client.chat.completions.create(
    model="meta-llama/Llama-3.2-11B-Vision-Instruct-Turbo",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "这张图里有什么？"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
    ]}]
)

这套接口设计与 OpenAI Chat Completions API 完全对齐，开发者从 OpenAI SDK 迁移到 Together SDK 成本极低，只需更换 base URL 和 API key 即可。

3.2 批量推理（Batches）：成本降低50%的秘密

3.3 模型微调（Fine-tuning）：在开源模型上训练自己的AI

这是 Together.ai 平台区别于大多数推理 API 的核心能力。SDK 支持：

全量微调（Full Fine-tuning）：更新模型全部参数，效果好但成本高、耗时长
LoRA 微调：仅训练低秩适配器，显存需求低至单卡 A100 80GB，适合大多数团队
多数据集格式支持：支持 general（纯文本）、conversation（对话）、instruction（指令）、preference（偏好）四种数据集格式
S3 兼容文件上传：支持分段并发上传（最大支持 50GB 文件），并自动验证 Parquet 文件列结构

3.4 代码解释器（Code Interpreter）：让AI真正执行代码

3.5 CLI 工具：命令行也能玩转AI

SDK 还内置了一个 Typer CLI，提供交互式命令行界面：

together chat completions.create --model meta-llama/Llama-4-Scout-17B-16E-Instruct
together files list
together fine_tuning retrieve --fine-tune-id ft-xxxx
together models list

CLI 对开发者来说非常实用，特别是在调试 API、查看模型列表、快速测试模型输出等场景。

四、技术质量评估

维度	评分	说明
代码质量	★★★★☆	遵循 PEP8 + Black 格式化，Pydantic v2 强类型约束，Mypy 静态检查
测试覆盖	★★★★☆	pytest 完整测试套件，包含 integration 和 unit 目录，pre-commit 检查
文档质量	★★★★★	官方文档详尽，README 包含所有功能的使用示例，配套官方迁移指南
类型安全	★★★★★	全程 Pydantic v2，所有请求/响应严格建模，IDE 自动补全体验优秀
兼容性	★★★★☆	Python 3.10+，同步/异步双通道，OpenAI SDK 接口对齐，迁移成本低

五、上手门槛分析

维度	说明
编程要求	Python 3.10+ 基础即可，无需深度学习知识
硬件要求	零 GPU 要求，纯客户端 SDK，所有计算在 Together 云端完成
API Key	需注册 Together.ai 账号（api.together.xyz），有免费额度
安装方式	`pip install together`，无其他依赖冲突
费用	调用按 token 计费，Batch API 半价，免费额度可申请

六、局限与注意事项

1. V1 版本已过时：目前 SDK V1 已标记 deprecated，官方新功能全部在 together-py（V2）。新项目应直接使用 V2。

2. 中国大陆访问限制：Together.ai 平台服务器位于境外，国内访问需要稳定的国际网络连接，部分区域可能存在延迟。

4. 模型可用性依赖平台：SDK 的能力上限受限于 Together.ai 平台支持的模型，部分前沿模型可能需要申请或等待排期。