项目概述

Together Python 由 Together Computer 团队开发和维护，旨在为开发者提供一套完整、简洁的 API 接口，使其能够轻松地将 Together AI 平台的各种 AI 能力集成到自己的应用程序中。

核心特性

资料来源：README.md:1-30

项目架构

Together Python 采用模块化设计，主要包含以下几个核心组件：

架构图

graph TD
    subgraph "客户端层"
        Python[Python 客户端]
        CLI[CLI 命令行工具]
        Async[异步客户端]
    end
    
    subgraph "资源模块"
        Chat[Chat Completions]
        Completions[Completions]
        Embeddings[Embeddings]
        Images[Images]
        Rerank[Reranking]
        FineTuning[Fine-Tuning]
    end
    
    subgraph "核心层"
        Requestor[API Requestor]
        FileManager[文件管理器]
        Error[错误处理]
    end
    
    subgraph "Together AI 平台"
        API[REST API]
        Models[模型服务]
    end
    
    Python --> Chat
    Python --> Completions
    Python --> Embeddings
    Python --> Images
    Python --> Rerank
    Python --> FineTuning
    
    CLI --> Chat
    CLI --> Completions
    CLI --> FineTuning
    
    Async --> Chat
    Async --> Completions
    
    Chat --> Requestor
    Completions --> Requestor
    Embeddings --> Requestor
    Images --> Requestor
    Rerank --> Requestor
    FineTuning --> Requestor
    
    Requestor --> API
    FineTuning --> FileManager
    FileManager --> API
    API --> Models

核心模块说明

#### 异常处理模块

项目定义了一套完整的异常类型体系，用于处理各种错误场景：

资料来源：src/together/error.py:1-60

#### 聊天补全模块

提供 Chat Completions API 接口，支持多种消息格式和工具调用：

response = client.chat.completions.create(
    model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
    messages=[{"role": "user", "content": "tell me about new york"}],
)

资料来源：README.md:30-40

#### 微调模块

提供完整的模型微调工作流程，包括价格估算、训练配置和检查点管理：

资料来源：src/together/resources/finetune.py:1-100

主要功能

1. 对话补全（Chat Completions）

支持单轮和多轮对话，以及多模态输入（文本+图像）：

graph LR
    A[用户消息] --> B[构建消息列表]
    B --> C[API 请求]
    C --> D{流式?}
    D -->|是| E[流式响应]
    D -->|否| F[完整响应]
    E --> G[逐块处理]
    F --> H[返回完整结果]

资料来源：src/together/resources/chat/completions.py:1-50

2. 补全（Completions）

提供传统的文本补全功能：

response = client.completions.create(
    model="codellama/CodeLlama-34b-Python-hf",
    prompt="Write a Next.js component with TailwindCSS for a header component.",
    max_tokens=200,
)

资料来源：README.md:80-90

3. 嵌入（Embeddings）

支持文本嵌入向量生成：

outputs = client.embeddings.create(
    model='togethercomputer/m2-bert-80M-8k-retrieval',
    input=texts
)

4. 图像生成（Image Generation）

提供图像生成能力：

response = client.images.generate(
    prompt="space robots",
    model="stabilityai/stable-diffusion-xl-base-1.0",
    steps=10,
    n=4,
)

5. 重排序（Reranking）

支持文档重排序功能：

outputs = client.rerank.create(
    model=model,
    query=query,
    documents=documents,
    top_n=top_n
)

6. 模型微调（Fine-Tuning）

提供完整的微调工作流程：

# 启动微调任务
together fine-tuning create \
  --training-file <FILE_ID> \
  --model meta-llama/Llama-4-Scout-17B-16E-Instruct \
  --n-epochs 3

#### 支持的微调方法

资料来源：src/together/resources/finetune.py:50-150

安装与配置

环境要求

• Python 3.10+
• Poetry 1.6.1+

安装步骤

1. 获取 API Key：访问 Together AI 注册页面 获取 API Key

1. 设置环境变量：

export TOGETHER_API_KEY=xxxxx

1. 安装依赖：

poetry install --with quality,tests

1. 设置 pre-commit：

pre-commit install

资料来源：CONTRIBUTING.md:1-30

使用方式

Python 客户端使用

from together import Together

# 初始化客户端
client = Together(api_key="xxxxx")

# 创建聊天请求
response = client.chat.completions.create(
    model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
    messages=[{"role": "user", "content": "Hello, how are you?"}]
)

print(response.choices[0].message.content)

异步客户端使用

from together import AsyncTogether

async_client = AsyncTogether()

tasks = [
    async_client.completions.create(model="...", prompt="..."),
    async_client.completions.create(model="...", prompt="...")
]

responses = await asyncio.gather(*tasks)

CLI 命令行使用

# 聊天补全
together chat.completions --message "Hello" --model meta-llama/Llama-4-Scout-17B-16E-Instruct

# 文本补全
together completions "Large language models are " --model meta-llama/Llama-4-Scout-17B-16E-Instruct

# 图像生成
together images generate "space robots" --model stabilityai/stable-diffusion-xl-base-1.0

# 文件操作
together files upload example.jsonl
together files list
together files retrieve <FILE_ID>

# 微调任务
together fine-tuning create --training-file <FILE_ID> --model <MODEL>
together fine-tuning list
together fine-tuning events <FINE_TUNE_ID>
together fine-tuning download <FINE_TUNE_ID>

错误处理

项目实现了完善的错误处理机制：

graph TD
    A[API 请求] --> B{响应状态}
    B -->|成功| C[返回结果]
    B -->|4xx 错误| D[客户端错误]
    B -->|5xx 错误| E[服务器错误]
    B -->|速率限制| F[RateLimitError]
    B -->|超时| G[Timeout]
    
    D --> H[TogetherException]
    E --> H
    F --> H
    G --> H

开发指南

本地开发设置

# 安装开发依赖
poetry install --with quality,tests

# 格式化和代码检查
make format

# 运行测试
make tests

测试说明

资料来源：CONTRIBUTING.md:30-60

技术规格

支持的模型类型

API 特性支持

项目结构

together-python/
├── src/together/
│   ├── __init__.py          # 主入口
│   ├── error.py             # 异常定义
│   ├── version.py           # 版本信息
│   ├── client.py            # 客户端实现
│   ├── filemanager.py       # 文件管理器
│   ├── resources/           # API 资源模块
│   │   ├── chat/
│   │   │   └── completions.py
│   │   ├── completions.py
│   │   ├── embeddings.py
│   │   ├── images.py
│   │   ├── rerank.py
│   │   └── finetune.py
│   ├── utils/
│   │   └── files.py         # 文件处理工具
│   └── cli/
│       └── api/             # CLI 命令
│           ├── chat.py
│           ├── completions.py
│           ├── finetune.py
│           └── ...
└── tests/                   # 测试文件

总结

Together Python 是一个功能全面、易于使用的 Python 客户端库，为开发者提供了与 Together AI 平台交互的便捷方式。通过统一的 Python API 和 CLI 工具，开发者可以轻松实现聊天补全、文本补全、嵌入生成、图像生成和模型微调等多种 AI 功能。项目采用模块化设计，具有良好的可扩展性和维护性，适合各类 AI 应用的开发和部署。

概述

together-python 是 Together AI 提供的官方 Python SDK，提供了 Python 客户端库和 CLI 工具两种使用方式。该库支持多种核心功能，包括对话补全、文本补全、图像生成、嵌入向量生成以及模型微调等。资料来源：README.md:1-10

环境要求

系统要求

依赖环境管理器说明

该项目使用 Poetry v1.6.1+ 作为依赖管理器。如果使用 Conda 或 Pyenv 作为环境或包管理器，安装 Poetry 后需要配置 Poetry 使用虚拟环境的 Python 解释器。资料来源：CONTRIBUTING.md:60-70

poetry config virtualenvs.prefer-active-python true

安装方式

方式一：通过 PyPI 安装（推荐）

使用 pip 直接安装 together-python 包：

pip install together

方式二：通过 Poetry 安装开发依赖

克隆仓库后，使用 Poetry 安装本地开发环境：

git clone https://github.com/togethercomputer/together-python.git
cd together-python
poetry install --with quality,tests

此命令会安装所有必要的依赖，包括：

• quality: 代码格式化和静态检查工具
• tests: 测试框架和测试依赖

资料来源：CONTRIBUTING.md:54-58

方式三：从源码安装

pip install git+https://github.com/togethercomputer/together-python.git

环境变量配置

获取 API Key

1. 访问 Together Playground: https://api.together.ai
2. 在设置页面创建 API Key: https://api.together.xyz/settings/api-keys

配置环境变量

Linux/macOS:

export TOGETHER_API_KEY=your_api_key_here

Windows (PowerShell):

$env:TOGETHER_API_KEY="your_api_key_here"

永久配置：

将上述命令添加到 shell 配置文件（~/.bashrc、~/.zshrc 或 ~/.profile）中。

资料来源：README.md:5-10

客户端初始化

基础客户端初始化

在代码中使用 API Key 初始化客户端：

from together import Together

# 使用环境变量中的 API Key
client = Together()

# 或显式传入 API Key
client = Together(api_key="your_api_key_here")

资料来源：README.md:13-18

异步客户端

对于需要异步处理的场景，使用 AsyncTogether 类：

from together import AsyncTogether

async_client = AsyncTogether()

CLI 客户端

CLI 工具在安装包后自动可用，无需额外配置。确保 TOGETHER_API_KEY 环境变量已设置即可。

开发环境配置

安装预提交钩子

项目使用 pre-commit 进行代码格式化和 linting 自动检查。安装开发依赖后，运行：

pre-commit install

这会在每次提交前自动执行格式化和检查。

资料来源：CONTRIBUTING.md:58-60

代码格式化和检查

提交代码前手动运行检查：

# 格式化代码
make format

# 运行测试
make tests

# 运行集成测试（需要 API Key，会产生费用）
make integration_tests

资料来源：CONTRIBUTING.md:40-50

可选依赖管理

项目采用可选依赖策略，大部分用户不会安装所有依赖。引入新依赖时应遵循以下流程：

``bash poetry add --optional [package_name] ``

1. 将依赖添加到可选组：

1. 在 pyproject.toml 中将依赖添加到 extended_testing extra

``bash poetry lock --no-update ``

1. 重新锁定依赖：

1. 添加至少导入该代码的单元测试

1. 使用 @pytest.mark.requires(package_name) 装饰需要该依赖的测试

资料来源：CONTRIBUTING.md:18-35

项目结构

together-python/
├── pyproject.toml          # 项目配置和依赖定义
├── src/
│   └── together/
│       ├── __init__.py     # 包初始化和导出
│       ├── error.py        # 异常定义
│       ├── constants.py    # 常量定义
│       ├── resources/      # 功能资源模块
│       │   ├── chat/       # 聊天补全
│       │   ├── completions.py  # 文本补全
│       │   ├── images.py   # 图像生成
│       │   ├── embeddings.py   # 嵌入向量
│       │   ├── rerank.py    # 重排序
│       │   └── finetune.py  # 模型微调
│       └── cli/            # CLI 工具实现
│           └── api/        # CLI 命令
└── tests/                  # 测试文件

配置验证

验证安装

import together

# 检查版本
print(together.__version__)

# 验证连接
client = Together()
models = client.models.list()
print(f"可用模型数量: {len(models.data)}")

常见配置错误

资料来源：src/together/error.py:1-50

工作流程图

graph TD
    A[开始] --> B{是否安装 SDK?}
    B -->|否| C[安装 together-python]
    C --> D{是否有 API Key?}
    D -->|否| E[申请 API Key]
    E --> F[配置环境变量]
    D -->|是| F
    F --> G[初始化客户端]
    G --> H{使用场景}
    H -->|同步| I[使用 Together 客户端]
    H -->|异步| J[使用 AsyncTogether 客户端]
    H -->|CLI| K[使用 together CLI]
    I --> L[调用 API]
    J --> L
    K --> L

下一步

• 快速开始指南 - 了解基本使用方法
• 聊天补全 - 对话功能详解
• 模型微调 - 自定义模型训练
• CLI 参考 - 命令行工具完整文档

概述

Together Python 客户端是一个轻量级且易于使用的 Python 库和命令行工具，为 Together AI 平台提供统一的 API 接口。该客户端架构采用分层设计，核心层负责 HTTP 通信和请求处理，资源层提供各类 AI 能力的抽象接口，CLI 层提供命令行交互能力。

客户端的核心设计目标包括：

• 简化 API 调用：通过 Pythonic 的接口封装底层 HTTP 请求细节
• 支持同步和异步操作：提供 Together 和 AsyncTogether 两种客户端实现
• 流式响应支持：原生支持流式输出，便于实时展示生成结果
• 完整的类型提示：使用 Pydantic 模型进行请求参数和响应数据的验证

资料来源：src/together/client.py

架构分层

整体架构图

graph TD
    A[客户端入口] --> B[Together / AsyncTogether]
    B --> C[资源层 Resources]
    C --> D[Chat Completions]
    C --> E[Completions]
    C --> F[Embeddings]
    C --> G[Images]
    C --> H[Fine-tuning]
    C --> I[Files]
    C --> J[Rerank]
    B --> K[APIRequestor]
    K --> L[HTTP 请求处理]
    L --> M[Together API]

核心组件

资料来源：src/together/client.py, src/together/abstract/api_requestor.py

客户端初始化

基本用法

from together import Together

# 使用环境变量中的 API Key
client = Together()

# 直接指定 API Key
client = Together(api_key="your-api-key-here")

客户端初始化时接受以下配置参数：

资料来源：src/together/client.py

异步客户端

from together import AsyncTogether

async_client = AsyncTogether()

# 在 async 函数中使用
async def main():
    response = await async_client.chat.completions.create(
        model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
        messages=[{"role": "user", "content": "Hello!"}]
    )

异步客户端继承自 AsyncHTTPHandler，支持使用 asyncio.gather 等工具进行并发请求。

资料来源：src/together/resources/__init__.py

请求处理流程

同步请求流程

sequenceDiagram
    participant C as Together 客户端
    participant R as Resources
    participant A as APIRequestor
    participant H as HTTP Handler
    
    C->>R: 调用 .chat.completions.create()
    R->>A: 创建 TogetherRequest
    A->>H: request_raw() / request()
    H->>H: 添加认证头
    H->>H: 处理重试逻辑
    H->>Together API: 发送 HTTP 请求
    Together API-->>H: 返回响应
    H-->>A: 解析响应数据
    A-->>R: 返回 TogetherResponse
    R-->>C: 转换为 Pydantic 模型

流式响应处理

stream = client.completions.create(
    model="codellama/CodeLlama-34b-Python-hf",
    prompt="Write a Next.js component",
    stream=True,
)

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

流式响应使用生成器模式，逐块返回数据。每个 chunk 都是一个 CompletionChunk 或 ChatCompletionChunk 对象。

资料来源：src/together/resources/completions.py, src/together/resources/chat/completions.py

API 请求器

APIRequestor 职责

APIRequestor 是底层的 HTTP 请求处理器，封装了所有与 Together API 的通信逻辑：

请求方法

# 同步请求
response, status_code, duration = requestor.request(
    options=TogetherRequest(
        method="POST",
        url="chat/completions",
        params=payload,
    ),
)

# 原始响应（用于文件下载等场景）
raw_response = requestor.request_raw(
    options=TogetherRequest(
        method="GET",
        url=file_url,
        headers={"Range": "bytes=0-1"},
    ),
)

资料来源：src/together/abstract/api_requestor.py

响应模型

统一响应结构

classDiagram
    class TogetherResponse {
        +Any data
        +int status_code
    }
    
    class ChatCompletionResponse {
        +str id
        +str object
        +int created
        +str model
        +list choices
        +Usage usage
    }
    
    class CompletionResponse {
        +str id
        +str object
        +int created
        +str model
        +list choices
        +Usage usage
    }
    
    TogetherResponse <|-- ChatCompletionResponse
    TogetherResponse <|-- CompletionResponse

响应模型字段

资料来源：src/together/together_response.py

资源层设计

资源模块概览

graph TD
    Resources --> Chat
    Resources --> Completions
    Resources --> Embeddings
    Resources --> Images
    Resources --> Files
    Resources --> FineTuning
    Resources --> Rerank
    Resources --> Models

资料来源：src/together/resources/__init__.py

聊天完成资源

聊天完成是最常用的功能之一，支持多种消息格式和工具调用：

# 简单文本消息
response = client.chat.completions.create(
    model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
    messages=[{"role": "user", "content": "tell me about new york"}],
)

# 多模态消息（文本+图像）
response = client.chat.completions.create(
    model="meta-llama/Llama-3.2-11B-Vision-Instruct-Turbo",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}}
        ]
    }]
)

资料来源：src/together/resources/chat/completions.py

文件管理

文件管理模块提供完整的上传、下载、列表查询等功能：

# 上传文件
response = client.files.upload(file=open("data.jsonl", "rb"))

# 检查文件
client.files.check(file_id)

# 下载文件内容
content = client.files.retrieve_content(file_id)

# 列出文件
files = client.files.list()

资料来源：src/together/filemanager.py

错误处理

异常层次结构

classDiagram
    class TogetherException {
        +str message
        +Any http_status
        +Any body
    }
    
    class AuthenticationError {
        <<extends TogetherException>>
    }
    
    class RateLimitError {
        <<extends TogetherException>>
    }
    
    class APIConnectionError {
        <<extends TogetherException>>
    }
    
    class Timeout {
        <<extends TogetherException>>
    }
    
    class APIError {
        <<extends TogetherException>>
    }

异常类型说明

from together.error import RateLimitError, AuthenticationError

try:
    response = client.chat.completions.create(
        model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
        messages=[{"role": "user", "content": "Hello"}],
    )
except AuthenticationError as e:
    print("Invalid API key")
except RateLimitError as e:
    print("Rate limit exceeded, please wait")

资料来源：src/together/error.py

配置管理

环境变量

客户端配置示例

from together import Together
import os

# 方式一：环境变量
client = Together()  # 自动读取 TOGETHER_API_KEY

# 方式二：直接传入
client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))

# 方式三：自定义配置
client = Together(
    api_key="your-key",
    base_url="https://api.together.xyz",
    timeout=120,
    max_retries=3
)

资料来源：src/together/client.py

最佳实践

1. 异步并发请求

import asyncio
from together import AsyncTogether

async_client = AsyncTogether()

async def batch_requests():
    tasks = [
        async_client.chat.completions.create(
            model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
            messages=[{"role": "user", "content": prompt}],
        )
        for prompt in prompts
    ]
    responses = await asyncio.gather(*tasks)
    return responses

2. 流式响应处理

stream = client.completions.create(
    model="codellama/CodeLlama-34b-Python-hf",
    prompt="Write a Next.js component",
    stream=True,
)

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

3. 错误重试机制

客户端内置自动重试机制，支持指数退避策略。默认配置：

• 最大重试次数：2
• 超时时间：600 秒
• 可通过自定义 httpx.Client 调整

资料来源：src/together/abstract/api_requestor.py

扩展性

自定义 HTTP 客户端

import httpx
from together import Together

# 使用自定义配置的 HTTP 客户端
custom_client = httpx.Client(
    timeout=httpx.Timeout(60.0, connect=10.0),
    proxies={"http://": "http://proxy.example.com:8080"},
)

client = Together(client=custom_client)

资源扩展

新功能可以通过扩展资源类来实现，所有资源类都遵循统一的接口模式：

class BaseResource:
    def __init__(self, client: TogetherClient) -> None:
        self._client = client

资料来源：src/together/resources/__init__.py

总结

Together Python 客户端采用清晰的分层架构设计，将 API 通信细节封装在 APIRequestor 中，对外提供直观的资源接口。核心设计原则包括：

1. 简洁易用：通过高级抽象简化 API 调用复杂度
2. 类型安全：使用 Pydantic 模型确保请求参数和响应数据的正确性
3. 灵活扩展：分层设计便于添加新功能和自定义行为
4. 完善的错误处理：层次化的异常体系便于精准捕获和处理错误

该架构既适合快速原型开发，也能满足生产环境对稳定性和性能的要求。

概述

Together Python SDK 的请求流程与抽象层是整个库的核心架构部分，负责处理所有与 Together API 的通信交互。该层通过分层设计实现了请求的发送、响应的处理、错误的捕获与转换，以及同步/异步操作的支持。开发者通过 Together 客户端实例发起各类请求（如聊天补全、文生图、嵌入等），而底层的抽象层则负责将高层 API 调用转换为底层的 HTTP 请求，并与 Together 服务器进行交互。

该架构的核心价值在于解耦与统一：上层资源（如 Completions、Chat、Embeddings 等）无需关心具体的网络通信细节，只需专注于业务逻辑参数的准备和响应数据的解析。所有底层网络通信、认证、超时重试等机制都由抽象层统一处理，确保了整个 SDK 的一致性与可维护性。

从架构层面看，Together SDK 采用了典型的客户端-请求者-响应三层模型。Together 客户端作为入口点，提供各类资源对象；资源对象负责构建请求参数并调用请求者；APIRequestor 则处理底层的 HTTP 通信，包括认证头的生成、请求发送、超时控制以及错误处理。最终，响应数据通过 TogetherResponse 和具体的响应模型类（如 ChatCompletionResponse、CompletionResponse）返回给调用者。

核心组件架构

Together SDK 的请求流程涉及多个核心组件，它们各司其职、协同工作。下表列出了主要组件及其职责：

Together 主类定义了所有支持的资源类型，包括 completions、chat、embeddings、files、images、models、fine_tuning、rerank、audio、batches、code_interpreter、evaluation 和 videos。每个资源都持有对底层客户端的引用，可以直接调用 APIRequestor 发起请求。这种设计使得添加新的 API 功能只需扩展资源类，而无需修改底层通信机制。

graph TD
    A[Together 客户端] --> B[资源层<br/>Completions/Chat/Embeddings...]
    B --> C[请求构建<br/>参数序列化]
    C --> D[APIRequestor<br/>抽象请求者]
    D --> E[HTTP 通信层<br/>requests/httpx]
    E --> F[Together API 服务器]
    F --> G[TogetherResponse<br/>原始响应]
    G --> H[响应解析<br/>Pydantic 模型]
    H --> I[业务响应对象<br/>ChatCompletion/Completion...]

请求流程详解

同步请求流程

同步请求是最基本的请求模式，适用于大多数使用场景。请求从客户端发起，经过资源层、请求构建层，最终由 APIRequestor 发送 HTTP 请求。以聊天补全为例，完整的请求流程如下：

1. 客户端实例化：用户创建 Together 客户端实例，可传入 api_key、base_url、timeout 等配置参数。若未显式提供，api_key 会自动从环境变量 TOGETHER_API_KEY 获取。
2. 资源调用：用户通过 client.chat.completions.create() 发起聊天补全请求，传入模型名称、消息列表等参数。
3. 参数构建：资源类将用户参数转换为 API 所需的格式，包括默认值填充、参数校验和序列化。
4. 请求发送：APIRequestor 接收 TogetherRequest 对象，构建完整的 HTTP 请求，包括认证头、内容类型等。
5. 响应处理：服务器响应后，APIRequestor 将原始响应包装为 TogetherResponse 对象返回。
6. 结果解析：资源类将 TogetherResponse 中的数据解析为具体的响应模型（如 ChatCompletionResponse），返回给用户。

在 client.py 中，Together 类的初始化逻辑展示了配置参数的优先级处理：

def __init__(
    self,
    *,
    api_key: str | None = None,
    base_url: str | None = None,
    timeout: float | None = None,
    max_retries: int | None = None,
    supplied_headers: Dict[str, str] | None = None,
) -> None:

配置参数按照以下优先级获取：显式传入的参数 > 环境变量 > 默认值。这种设计既提供了灵活性，又保证了向后兼容性。

异步请求流程

Together SDK 完全支持异步操作，通过 AsyncTogether 类提供异步版本的客户端。异步请求在处理大量并发请求时具有显著优势，能够有效利用系统资源并提高吞吐量。

异步请求的核心差异在于 APIRequestor 使用 arequest 方法而非 request 方法。在 resources/chat/completions.py 中可以看到异步请求的实现模式：

response, _, _ = await requestor.arequest(
    options=TogetherRequest(
        method="POST",
        url="chat/completions",
        params=parameter_payload,
    ),
    stream=stream,
)

异步方法返回协程对象，配合 asyncio 或 aiohttp 等异步框架使用。资源类可以将异步请求封装为异步生成器，便于处理流式响应。流式响应通过异步生成器实现，每次迭代返回一个新的响应块，直到所有数据发送完毕。

sequenceDiagram
    participant User as 用户代码
    participant Client as AsyncTogether
    participant Resource as 资源类
    participant Requestor as APIRequestor
    participant Server as Together API
    
    User->>Client: 异步调用
    Client->>Resource: create()
    Resource->>Resource: 构建参数
    Resource->>Requestor: arequest()
    Requestor->>Server: async HTTP POST
    Server-->>Requestor: 流式响应
    loop 流式处理
        Requestor-->>Resource: 异步生成器
        Resource-->>User: ChatCompletionChunk
    end

流式响应处理

流式响应是 Together API 的重要特性，特别适用于需要实时展示生成内容的场景，如聊天机器人和代码补全。SDK 对流式响应的处理采用了异步生成器模式，既保证了实时性，又提供了良好的编程接口。

在 resources/completions.py 中，流式响应的处理逻辑展示了响应类型的动态判断：

if stream:
    # must be an iterator
    assert not isinstance(response, TogetherResponse)
    return (CompletionChunk(**line.data) async for line in response)
assert isinstance(response, TogetherResponse)
return CompletionResponse(**response.data)

当启用流式传输时，响应对象不再是单一的 TogetherResponse，而是变成了一个异步迭代器。每次迭代从服务器接收一个数据块，解析为对应的 Chunk 类型（如 CompletionChunk 或 ChatCompletionChunk）。这种设计允许用户实时处理响应数据，无需等待完整响应生成。

抽象层设计

APIRequestor 职责

APIRequestor 是请求流程抽象层的核心组件，负责所有底层的 HTTP 通信逻辑。它封装了认证、请求发送、超时控制、重试机制和错误处理等复杂逻辑，为上层资源类提供简洁统一的接口。

APIRequestor 的主要职责包括：

• 认证管理：自动从环境变量或客户端配置获取 API 密钥，生成符合 Together API 规范的认证头。在 filemanager.py 中可以看到认证头的生成方式：together.utils.get_headers(method, requestor.api_key)
• 请求发送：支持同步的 request 方法和异步的 arequest 方法，处理不同类型的 HTTP 请求（GET、POST 等）
• 参数传递：接收 TogetherRequest 对象作为请求配置，包含 URL、HTTP 方法、查询参数、请求体等
• 响应包装：将原始 HTTP 响应转换为 TogetherResponse 对象，统一响应处理流程
• 错误转换：捕获 HTTP 错误和业务错误，转换为合适的异常类型抛出

APIRequestor 的设计遵循了单一职责原则，将网络通信的复杂性隔离在抽象层内部。上层代码只需关注业务逻辑，无需直接处理 HTTP 协议的细节。这种设计也便于单元测试，因为可以使用 Mock 对象替代真实的网络请求。

TogetherRequest 配置对象

TogetherRequest 是请求配置的数据类，封装了发起 HTTP 请求所需的所有信息。它是连接上层业务逻辑与底层网络通信的桥梁，确保了请求参数的完整性和一致性。

TogetherRequest 通常包含以下字段：

通过使用 model_dump(exclude_none=True) 方法，可以方便地将请求配置序列化为字典，去除 None 值，保持请求体的简洁。

TogetherResponse 响应包装

TogetherResponse 是对原始 HTTP 响应的封装类，它将底层的响应状态码、响应头和响应体统一包装在一起。这种设计简化了响应数据的访问方式，并提供了类型安全的数据访问接口。

TogetherResponse 的主要属性包括：

• status_code：HTTP 状态码，用于判断请求是否成功
• headers：响应头信息，包含内容类型、字符编码等元数据
• data：响应体数据，已经过 JSON 解析的字典或列表

在非流式响应场景下，资源类通过 TogetherResponse.data 访问响应内容，并使用 Pydantic 模型进行数据验证和解析。这种模式确保了响应数据的结构符合预期，提供了自动的类型转换和验证功能。

错误处理机制

异常层次结构

Together SDK 定义了一套完整的异常层次结构，从基类 TogetherException 派生出各类具体异常。这种设计允许调用者采用宽捕获或精确捕获的方式处理错误，既可以捕获所有 Together 相关错误，也可以针对特定错误类型进行处理。

在 error.py 中定义的主要异常类型包括：

异常类的构造函数接收多种类型的消息参数，包括 TogetherErrorResponse（服务器返回的错误响应结构）、Exception（原始异常对象）、字符串消息或 RequestException。这种灵活性使得错误信息可以来自不同的来源，便于调试和日志记录。

错误处理流程

错误处理贯穿整个请求流程，在多个层面进行：

1. HTTP 层错误捕获：APIRequestor 捕获底层 HTTP 异常（如连接超时、DNS 解析失败等），转换为 APIConnectionError 或 Timeout。
2. HTTP 状态码检查：响应返回后检查状态码，非 2xx 状态码会触发异常。在 filemanager.py 中可以看到：response.raise_for_status() 用于触发 HTTP 状态码异常。
3. 业务错误解析：Together API 返回的错误响应会解析为结构化的错误信息，便于调用者理解错误原因。
4. 重试机制：APIRequestor 实现了一定的重试逻辑，对于临时性错误（如 503 Service Unavailable）会自动重试。

graph TD
    A[发起请求] --> B{网络正常?}
    B -->|否| C[APIConnectionError]
    B -->|是| D{状态码 2xx?}
    D -->|否| E{可重试状态码?}
    D -->|是| F{流式响应?}
    F -->|否| G[TogetherResponse]
    F -->|是| H[异步生成器]
    E -->|是| I[重试请求]
    E -->|否| J[APIError]
    I --> A

文件管理中的请求流程

文件管理模块展示了请求流程的另一个应用场景，包括文件上传、下载和元数据获取等操作。该模块使用了重定向机制来处理大文件上传，这是标准的 multipart/form-data 上传模式。

上传流程

文件上传采用了重定向模式：首先向 API 发起初始化请求，获取预签名的上传 URL；然后直接向该 URL 上传文件内容；最后确认上传完成。这种模式可以将大文件上传的负载分散到对象存储服务，减轻 API 服务器的压力。

在 filemanager.py 中，get_upload_url 方法展示了重定向流程的实现：

response = requestor.request_raw(
    options=TogetherRequest(
        method=method,
        url=url,
        params=data,
        allow_redirects=False,
        override_headers=True,
        headers=headers,
    ),
    remaining_retries=MAX_RETRIES,
)

设置 allow_redirects=False 使得响应返回重定向头而非自动跟随，SDK 可以获取 Location 头获取实际的 upload URL 和文件 ID。

下载流程

文件下载支持断点续传和并发控制。通过发送 Range 请求获取文件大小信息，然后使用 FileLock 防止同一文件的并发下载。下载过程中使用临时文件，写入完成后原子性地重命名，确保文件完整性。

参数构建与序列化

资源类在发起请求前，需要将用户友好的参数转换为 API 所需的格式。这一过程包括默认值填充、参数校验、类型转换和序列化。

以聊天补全为例，参数构建在资源类中完成：

parameter_payload = ChatCompletionCreateParams(
    model=model,
    messages=messages,
    temperature=temperature,
    max_tokens=max_tokens,
    top_p=top_p,
    ...
).model_dump(exclude_none=True)

使用 Pydantic 的 model_dump(exclude_none=True) 方法可以方便地生成 API 兼容的 JSON 字典，自动排除值为 None 的可选参数。这种模式既保证了参数的规范性，又提供了灵活的默认值处理。

总结

Together Python SDK 的请求流程与抽象层通过分层设计实现了优雅的架构：主客户端提供统一入口，资源类封装业务逻辑，请求者抽象处理底层通信细节。这种设计既保证了代码的可读性和可维护性，又为扩展新功能提供了清晰的方向。

核心的抽象包括 APIRequestor 负责 HTTP 通信、TogetherRequest 封装请求配置、TogetherResponse 包装响应数据、TogetherException 及其子类处理错误。这些组件协同工作，为开发者提供了简洁而强大的 API 调用体验。开发者无需关心网络通信的复杂性，只需关注业务逻辑的实现，通过高层 API 即可完成与 Together 平台的所有交互。

概述

聊天补全 API（Chat Completions API）是 together-python 客户端库的核心功能之一，提供与 Together 平台上的大语言模型进行交互的统一接口。该 API 基于 OpenAI 兼容的聊天补全格式，支持文本对话、多模态输入（图像/视频）、流式输出、异步调用以及日志概率获取等高级功能。

在 together-python 架构中，Together 客户端类通过 chat 属性暴露聊天补全功能，底层由 resources.Chat 模块实现，具体逻辑封装在 ChatCompletions 类中。资料来源：src/together/client.py:1-30

核心组件架构

模块依赖关系

graph TD
    A[Together 客户端] --> B[resources.Chat]
    B --> C[ChatCompletions 类]
    C --> D[types/chat_completions.py]
    C --> E[requestor 请求模块]
    
    F[CLI chat 命令] --> C

客户端集成

Together 类在初始化时自动绑定所有资源端点，包括聊天补全功能：

资料来源：src/together/client.py:10-22

主要功能特性

1. 基础文本对话

聊天补全 API 支持最简单的文本消息交互，使用 messages 参数传递对话历史：

from together import Together

client = Together()

response = client.chat.completions.create(
    model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
    messages=[{"role": "user", "content": "tell me about new york"}],
)
print(response.choices[0].message.content)

资料来源：README.md

2. 多模态消息支持

API 支持在同一请求中传递多种内容类型，包括文本、图像 URL 和视频 URL：

#### 带图像的多模态示例

response = client.chat.completions.create(
    model="meta-llama/Llama-3.2-11B-Vision-Instruct-Turbo",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What's in this image?"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://huggingface.co/datasets/patrickvonplaten/random_img/resolve/main/yosemite.png"
                }
            }
        ]
    }]
)

#### 带视频的多模态示例

response = client.chat.completions.create(
    model="Qwen/Qwen2.5-VL-72B-Instruct",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What's happening in this video?"
            },
            {
                "type": "video_url",
                "video_url": {
                    "url": "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerFun.mp4"
                }
            }
        ]
    }]
)

资料来源：README.md

3. 流式输出

启用流式模式后，API 以增量方式返回生成的内容，适合需要实时展示的交互场景：

stream = client.chat.completions.create(
    model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
    messages=[{"role": "user", "content": "tell me about new york"}],
    stream=True,
)

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

资料来源：README.md

4. 异步调用

通过 AsyncTogether 客户端实现并发请求处理：

import asyncio
from together import AsyncTogether

async_client = AsyncTogether()

async def async_chat_completion(messages):
    tasks = [
        async_client.chat.completions.create(
            model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
            messages=[{"role": "user", "content": message}],
        )
        for message in messages
    ]
    responses = await asyncio.gather(*tasks)
    return responses

资料来源：README.md

5. 日志概率（Logprobs）

Logprobs 功能允许获取 token 级别的生成概率，用于评估模型输出的置信度：

response = client.chat.completions.create(
    model="meta-llama/Llama-3.2-3B-Instruct-Turbo",
    messages=[{"role": "user", "content": "tell me about new york"}],
    logprobs=1
)

日志概率的主要应用场景包括：

资料来源：README.md

API 参数详解

核心请求参数

资料来源：src/together/resources/chat/completions.py

惩罚参数

资料来源：src/together/cli/api/chat.py

高级参数

资料来源：src/together/resources/chat/completions.py

请求处理流程

同步请求流程

sequenceDiagram
    participant Client as Together 客户端
    participant API as Chat Completions API
    participant Backend as Together 后端
    
    Client->>API: client.chat.completions.create(params)
    API->>API: 验证参数，构建请求
    API->>Backend: POST /chat/completions
    Backend-->>API: 返回 ChatCompletionResponse
    API-->>Client: 返回最终响应对象
    
    Note over API,Backend: stream=True 时
    API->>Backend: POST /chat/completions (stream=true)
    Backend-->>API: 流式事件流
    API-->>Client: 异步生成器 (AsyncGenerator)

响应对象结构

ChatCompletionResponse {
    id: str                    # 请求唯一标识
    object: str                # 对象类型
    created: int               # 创建时间戳
    model: str                 # 实际使用的模型
    choices: List[Choice]      # 生成结果列表
    usage: Usage               # Token 使用统计
}

Choice {
    index: int                 # 结果索引
    message: Message           # 完整消息内容
    logprobs: Logprobs | None  # 日志概率（可选）
    finish_reason: str         # 结束原因
}

资料来源：src/together/types/chat_completions.py

CLI 命令行接口

通过 together CLI 可以直接调用聊天补全功能：

together chat.completions \
  --message "What is machine learning?" \
  --model meta-llama/Llama-4-Scout-17B-16E-Instruct \
  --max-tokens 512

CLI 可用选项

资料来源：src/together/cli/api/chat.py

完整使用示例

示例一：基础聊天

from together import Together

client = Together(api_key="your-api-key")

response = client.chat.completions.create(
    model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What are the top 3 things to do in San Francisco?"}
    ],
    temperature=0.7,
    max_tokens=256
)

print(response.choices[0].message.content)

示例二：多轮对话

messages = [
    {"role": "system", "content": "You are a Python expert."},
    {"role": "user", "content": "Explain what a decorator is."},
    {"role": "assistant", "content": "A decorator in Python is a function that..."},
    {"role": "user", "content": "Give me an example."}
]

response = client.chat.completions.create(
    model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
    messages=messages
)

示例三：并发请求

import asyncio
from together import AsyncTogether

async def batch_chat():
    async_client = AsyncTogether()
    
    queries = [
        "What is AI?",
        "What is ML?",
        "What is DL?"
    ]
    
    tasks = [
        async_client.chat.completions.create(
            model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
            messages=[{"role": "user", "content": q}]
        )
        for q in queries
    ]
    
    results = await asyncio.gather(*tasks)
    
    for i, response in enumerate(results):
        print(f"Q{i+1}: {queries[i]}")
        print(f"A{i+1}: {response.choices[0].message.content}\n")

asyncio.run(batch_chat())

错误处理

聊天补全 API 可能抛出的异常类型定义于 src/together/error.py：

from together import Together
from together.error import RateLimitError, AuthenticationError

client = Together()

try:
    response = client.chat.completions.create(
        model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
        messages=[{"role": "user", "content": "Hello"}]
    )
except AuthenticationError:
    print("请检查 API 密钥是否正确设置")
except RateLimitError:
    print("请求频率超限，请稍后重试")
except Exception as e:
    print(f"发生错误: {e}")

资料来源：src/together/error.py

最佳实践

1. 环境变量配置：将 API 密钥存储在环境变量 TOGETHER_API_KEY 中，避免硬编码
2. 流式响应处理：对于长文本生成，使用流式模式提升用户体验
3. 错误重试：结合指数退避策略处理临时性网络错误
4. 资源清理：异步操作完成后确保正确关闭连接
5. 多模态优化：图像输入时使用合理的分辨率以平衡质量和延迟

相关资源

• SDK 文档：Together Python SDK
• API 平台：api.together.xyz
• 模型列表：together models list 或 client.models.list()

概述

文本补全 API（Completions API）是 Together Python 客户端库的核心功能之一，提供对大型语言模型文本生成能力的访问。该 API 允许开发者通过简单的接口调用，向 Together 平台上的各种语言模型发送补全请求，并获取生成的文本内容。

核心组件架构

文本补全 API 的架构涉及多个协同工作的组件，从客户端入口到最终的 API 请求处理。

graph TD
    A[开发者代码] --> B[Together 客户端实例]
    B --> C[completions 资源对象]
    C --> D[Completions.create 方法]
    D --> E[请求参数构建]
    E --> F[API 请求发送]
    F --> G[Together API 服务器]
    G --> H[CompletionResponse]
    H --> I[开发者获取结果]
    
    style A fill:#e1f5fe
    style G fill:#fff3e0
    style I fill:#e8f5e9

主要组件说明

客户端集成

Together 主客户端类通过 completions 属性集成了文本补全功能。

class Together:
    completions: resources.Completions
    # ... 其他资源

资料来源：src/together/client.py:1-50

初始化与认证

客户端支持通过多种方式配置 API 密钥：

from together import Together

# 方式一：通过参数直接传入
client = Together(api_key="your-api-key")

# 方式二：通过环境变量自动读取
# 需要设置 TOGETHER_API_KEY 环境变量
client = Together()

API 方法详解

创建补全请求

completions.create() 是文本补全 API 的核心方法，支持同步和流式两种模式。

#### 方法签名

async def create(
    self,
    *,
    model: str,
    prompt: str,
    max_tokens: int | None = None,
    temperature: float | None = None,
    top_p: int | None = None,
    top_k: int | None = None,
    stop: str | list[str] | None = None,
    repetition_penalty: float | None = None,
    presence_penalty: float | None = None,
    frequency_penalty: float | None = None,
    min_p: float | None = None,
    stream: bool = False,
    logprobs: int | None = None,
    echo: bool = False,
    n: int | None = None,
    safety_model: str | None = None,
    response_format: dict | None = None,
    tools: list[dict] | None = None,
    tool_choice: str | dict | None = None,
    **kwargs,
) -> CompletionResponse | AsyncGenerator[CompletionChunk, None]

资料来源：src/together/resources/completions.py:1-150

#### 参数说明

使用模式

基础文本补全

最基本的文本补全调用，返回完整的补全结果：

from together import Together

client = Together()

response = client.completions.create(
    model="codellama/CodeLlama-34b-Python-hf",
    prompt="Write a Next.js component with TailwindCSS for a header component.",
    max_tokens=512,
)

print(response.choices[0].text)

资料来源：README.md:1-100

流式输出

流式模式允许实时获取生成的令牌，适合需要即时反馈的场景：

from together import Together

client = Together()

stream = client.completions.create(
    model="codellama/CodeLlama-34b-Python-hf",
    prompt="Write a Next.js component with TailwindCSS for a header component.",
    stream=True,
)

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

资料来源：README.md:1-100

#### 流式输出流程图

sequenceDiagram
    participant 客户端
    participant API
    participant 模型
    
    客户端->>API: POST /completions (stream=True)
    API->>模型: 转发请求
    模型-->>API: 流式令牌 1
    API-->>客户端: CompletionChunk 1
    模型-->>API: 流式令牌 2
    API-->>客户端: CompletionChunk 2
    模型-->>API: 流式令牌 N
    API-->>客户端: CompletionChunk N
    模型-->>API: [DONE]
    API-->>客户端: 流结束信号

异步并发请求

对于需要同时处理多个补全请求的场景，可以使用异步客户端：

import asyncio
from together import AsyncTogether

async_client = AsyncTogether()

prompts = [
    "Write a Next.js component with TailwindCSS for a header component.",
    "Write a python function for the fibonacci sequence",
]

async def async_completions(prompts):
    tasks = [
        async_client.completions.create(
            model="codellama/CodeLlama-34b-Python-hf",
            prompt=prompt,
        )
        for prompt in prompts
    ]
    responses = await asyncio.gather(*tasks)

    for response in responses:
        print(response.choices[0].text)

asyncio.run(async_completions(prompts))

资料来源：README.md:1-100

CLI 命令行接口

Together CLI 提供了命令行方式的文本补全功能：

together completions \
  "Large language models are " \
  --model meta-llama/Llama-4-Scout-17B-16E-Instruct \
  --max-tokens 512 \
  --stop "."

资料来源：README.md:1-100

CLI 参数选项

资料来源：src/together/cli/api/completions.py:1-150

响应数据结构

完整响应

当 stream=False 时，返回 CompletionResponse 对象：

@dataclass
class CompletionResponse:
    id: str
    choices: List[CompletionChoice]
    model: str
    usage: CompletionUsage
    created: int
    object: str = "text_completion"

流式响应

当 stream=True 时，返回 CompletionChunk 对象的异步生成器：

@dataclass
class CompletionChunk:
    id: str
    choices: List[CompletionChoicesChunk]
    model: str
    created: int
    object: str = "text_completion.chunk"

每个 CompletionChoicesChunk 包含 delta 字段，其中 delta.content 包含新生成的文本片段：

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

资料来源：src/together/resources/completions.py:1-150

错误处理

文本补全 API 可能抛出多种异常类型，继承自 TogetherException 基类：

graph TD
    A[TogetherException] --> B[RateLimitError]
    A --> C[AuthenticationError]
    A --> D[APIConnectionError]
    A --> E[Timeout]
    A --> F[InvalidRequestError]

资料来源：src/together/error.py:1-100

错误处理示例

from together import Together
from together.error import RateLimitError, APIConnectionError

client = Together()

try:
    response = client.completions.create(
        model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
        prompt="Hello, world!",
    )
except RateLimitError:
    print("请求频率超限，请稍后重试")
except APIConnectionError:
    print("网络连接失败，请检查网络")
except Exception as e:
    print(f"发生错误: {e}")

最佳实践

参数调优建议

性能优化

1. 使用流式输出：对于需要实时反馈的场景，启用 stream=True
2. 合理设置 max_tokens：避免生成过长文本造成不必要的资源消耗
3. 使用异步客户端：处理批量请求时使用 AsyncTogether
4. 缓存模型响应：对于相同提示的重复请求考虑实现缓存机制

安全考虑

1. 设置 safety_model：对敏感内容使用安全模型过滤
2. 限制输出长度：通过 max_tokens 控制最大生成长度
3. 使用停止序列：通过 stop 参数避免生成不期望的内容

功能概述

Together Python SDK 的多模态功能主要包括以下几个模块：

资料来源：src/together/client.py:25-38

架构设计

客户端架构

Together SDK 采用模块化架构，各个多模态功能通过独立的资源类实现：

graph TD
    A[Together 客户端] --> B[chat 聊天模块]
    A --> C[images 图像模块]
    A --> D[code_interpreter 代码解释器]
    A --> E[videos 视频模块]
    A --> F[audio 音频模块]
    
    B --> B1[文本处理]
    B --> B2[多图像处理]
    
    C --> C1[图像生成]
    C --> C2[参考图像支持]

图像生成功能

基本用法

图像生成模块允许通过文本提示词生成图像，支持自定义模型、尺寸、步数和数量等参数。

from together import Together

client = Together()

response = client.images.generate(
    prompt="space robots",
    model="stabilityai/stable-diffusion-xl-base-1.0",
    steps=10,
    n=4,
)
print(response.data[0].b64_json)

资料来源：README.md

CLI 使用方式

通过命令行也可以调用图像生成功能：

together images generate \
  "space robots" \
  --model stabilityai/stable-diffusion-xl-base-1.0 \
  --n 4

图像生成参数

资料来源：src/together/resources/images.py

请求处理流程

sequenceDiagram
    participant Client
    participant Images
    participant APIRequestor
    participant Together API
    
    Client->>Images: images.generate(prompt, model, ...)
    Images->>Images: 构建 ImageRequest
    Images->>APIRequestor: arequest(POST, images/generations)
    APIRequestor->>Together API: HTTP POST
    Together API-->>APIRequestor: ImageResponse
    APIRequestor-->>Images: TogetherResponse
    Images-->>Client: ImageResponse

聊天多模态功能

多模态消息格式

聊天模块支持多模态消息，消息内容可以是纯文本，也可以是包含文本和图像URL的列表结构。

from together import Together

client = Together()

response = client.chat.completions.create(
    model="meta-llama/Llama-3.2-11B-Vision-Instruct-Turbo",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What's in this image?"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://example.com/image.png"
                }
            }
        ]
    }]
)
print(response.choices[0].message.content)

资料来源：README.md

内容类型验证

系统对多模态内容有严格的验证规则：

资料来源：src/together/utils/files.py

数据格式示例

# 单文本消息
{"role": "user", "content": "普通文本消息"}

# 多模态消息（文本+图像）
{
    "role": "user",
    "content": [
        {"type": "text", "text": "描述这张图片"},
        {"type": "image_url", "image_url": {"url": "https://..."}}
    ]
}

代码解释器

代码解释器模块支持执行包含多模态数据的代码，能够处理图像等多媒体内容。

from together import Together

client = Together()

response = client.code_interpreter.run(
    input="分析这张图片并返回描述",
    images=[base64_image_data],
    model="codellama/CodeLlama-34b-Python-hf",
)
print(response)

资料来源：examples/code_interpreter_demo.py

视频生成功能

视频生成模块提供视频内容创作能力：

from together import Together

client = Together()

response = client.videos.generate(
    prompt="宇航员在太空站工作",
    model="some-video-model",
    duration=5,
)

资料来源：src/together/resources/videos.py

音频功能

音频模块支持音频相关的数据处理：

from together import Together

client = Together()

# 音频相关功能调用
response = client.audio.transcribe(
    file="audio.wav",
    model="whisper-model"
)

资料来源：src/together/resources/audio/__init__.py

工作流程图

多模态请求处理流程

graph TD
    A[开始请求] --> B[验证 API Key]
    B --> C[构建请求参数]
    C --> D{请求类型}
    
    D -->|图像生成| E[调用 images.generate]
    D -->|聊天多模态| F[调用 chat.completions.create]
    D -->|代码解释| G[调用 code_interpreter.run]
    D -->|视频生成| H[调用 videos.generate]
    
    E --> I[POST /images/generations]
    F --> J[POST /chat/completions]
    G --> K[POST /code_interpreter]
    H --> L[POST /videos/generations]
    
    I --> M[返回 ImageResponse]
    J --> N[返回 ChatCompletionResponse]
    K --> O[返回执行结果]
    L --> P[返回 VideoResponse]
    
    M --> Q[结束]
    N --> Q
    O --> Q
    P --> Q

错误处理

SDK 提供了多层次的错误处理机制：

资料来源：src/together/error.py

最佳实践

1. 图像大小优化：在上传图像前进行压缩，避免超过 10MB 限制
2. 提示词编写：使用清晰、具体的描述以获得更好的生成效果
3. 种子使用：当需要复现结果时，设置固定的 seed 值
4. 批量处理：利用 n 参数一次性生成多张图像，提高效率

总结

Together Python SDK 的多模态功能提供了统一、便捷的接口来访问各种生成式 AI 能力。通过模块化的设计，开发者可以根据需求灵活调用图像生成、多模态聊天、代码解释器、视频生成和音频处理等功能。所有功能都遵循一致的 API 设计规范，便于集成到各类应用场景中。

概述

嵌入（Embeddings）与重排序（Reranking）是 Together Python 库中用于增强检索能力的两大核心功能模块。它们共同构成了语义搜索和文档匹配的技术基础，使开发者能够将文本转换为高维向量表示，并通过相关性评分对候选结果进行排序优化。

Together Python 客户端通过统一的接口封装了这些功能，支持同步和异步两种调用方式，便于集成到各类应用场景中。嵌入功能主要用于将文本转换为稠密向量，而重排序功能则在此基础上对检索结果进行二次优化，提升最终结果的相关性。

架构设计

客户端集成

Together 客户端类在初始化时自动配置了嵌入和重排序资源。客户端采用模块化设计，将不同功能封装为独立的资源类，通过统一的方式对外提供服务。

graph TD
    A[Together 客户端] --> B[Embeddings 嵌入模块]
    A --> C[Rerank 重排序模块]
    B --> D[向量嵌入生成]
    C --> E[相关性评分计算]
    D --> F[语义相似度匹配]
    E --> G[结果重排序]
    F --> G

客户端类中声明了以下相关属性，用于支持嵌入和重排序功能：

资料来源：src/together/client.py:18-35

错误处理机制

嵌入与重排序模块共享统一的异常处理体系。所有自定义异常均继承自 TogetherException 基类，确保错误信息的一致性和可追溯性。

资料来源：src/together/error.py:1-60

嵌入功能详解

功能概述

嵌入功能将文本转换为固定维度的稠密向量，这种向量表示能够捕捉文本的语义信息。在自然语言处理领域，向量嵌入是语义搜索、文本相似度计算、聚类分析等任务的基础。通过 Together 平台提供的嵌入模型，开发者可以将任意文本转换为可计算的数值向量。

使用方式

#### 基础用法

from typing import List
from together import Together

client = Together()

def get_embeddings(texts: List[str], model: str) -> List[List[float]]:
    texts = [text.replace("\n", " ") for text in texts]
    outputs = client.embeddings.create(model=model, input=texts)
    return [outputs.data[i].embedding for i in range(len(texts))]

input_texts = ['Our solar system orbits the Milky Way galaxy at about 515,000 mph']
embeddings = get_embeddings(input_texts, model='togethercomputer/m2-bert-80M-8k-retrieval')

资料来源：README.md:65-75

#### 核心参数说明

#### 处理流程

嵌入处理流程包含以下关键步骤：

1. 文本预处理：移除换行符等特殊字符，确保输入格式统一
2. API 调用：通过 client.embeddings.create() 发起请求
3. 响应解析：从返回结果中提取 embedding 向量数据
4. 结果返回：以浮点数列表形式输出向量

支持的模型

Together 平台提供多种嵌入模型，常见选择包括 togethercomputer/m2-bert-80M-8k-retrieval 等专门针对检索任务优化的模型。开发者可根据精度、速度和成本需求选择合适的模型。

重排序功能详解

功能概述

重排序（Reranking）是信息检索领域的重要技术。当初始检索返回多个候选文档后，重排序模型会对这些文档进行相关性评分，并按照评分高低重新排列，从而将最相关的文档优先展示给用户。

Together 平台集成了高质量的重排序模型（如 Salesforce/Llama-Rank-V1），能够显著提升检索系统的最终效果。重排序通常作为第二阶段处理，位于初步向量检索之后。

使用方式

from typing import List
from together import Together

client = Together()

def get_reranked_documents(
    query: str, 
    documents: List[str], 
    model: str, 
    top_n: int = 3
) -> List[str]:
    outputs = client.rerank.create(
        model=model, 
        query=query, 
        documents=documents, 
        top_n=top_n
    )
    # sort by relevance score and returns the original docs
    return [
        documents[i] 
        for i in [x.index for x in sorted(
            outputs.results, 
            key=lambda x: x.relevance_score, 
            reverse=True
        )]
    ]

query = "What is the capital of the United States?"
documents = ["New York", "Washington, D.C.", "Los Angeles"]

reranked_documents = get_reranked_documents(
    query, 
    documents, 
    model='Salesforce/Llama-Rank-V1', 
    top_n=1
)

资料来源：README.md:80-100

#### 核心参数说明

#### 返回结果结构

重排序结果包含每个文档的索引位置和相关性评分：

组合工作流

嵌入与重排序通常组合使用，形成完整的检索管道。这种两阶段检索架构能够兼顾召回率和精确率：

graph LR
    A[用户查询] --> B[嵌入阶段]
    B --> C[向量相似度检索]
    C --> D[候选文档集]
    D --> E[重排序阶段]
    E --> F[最终排序结果]
    
    G[文档库] --> H[文档嵌入]
    H --> C

典型应用场景

异步调用支持

Together Python 库同时支持异步调用方式，便于在异步应用框架中集成使用。异步客户端 AsyncTogether 提供了与非异步版本相同的接口设计，确保开发体验的一致性。

import asyncio
from together import AsyncTogether

async_client = AsyncTogether()

async def async_rerank_example(query: str, documents: List[str]):
    results = await async_client.rerank.create(
        model='Salesforce/Llama-Rank-V1',
        query=query,
        documents=documents,
        top_n=5
    )
    return results

最佳实践

文本预处理

在调用嵌入功能前，建议对输入文本进行标准化处理：

• 移除多余的换行符和空白字符
• 统一文本编码格式
• 限制单条文本的最大长度以符合模型要求

性能优化建议

错误处理

集成时应妥善处理各类异常情况：

• 网络异常：实现重试机制
• 频率限制：遵守 API 调用频率约束
• 输入验证：确保文档列表非空且格式正确

相关资源

更多关于嵌入和重排序的详细文档，请参考 Together 官方文档：

• 嵌入功能概述
• 微调功能与文件上传

资料来源：README.md:100-102

功能概述

Together AI 的文件管理 API 主要服务于以下核心场景：

1. 微调数据管理：上传训练数据集以进行模型微调
2. 文件元数据查询：查看已上传文件的详细信息
3. 文件内容检索：获取已上传文件的具体内容
4. 存储空间管理：删除不再需要的文件以释放空间

文件管理模块在整个 SDK 架构中属于基础资源层，被 FineTuning（微调）和 Files（文件）两个核心资源类所依赖。客户端通过 Together 类的 files 属性访问这些功能。

graph LR
    A[用户代码] --> B[Together 客户端]
    B --> C[Files 资源类]
    C --> D[Together API]
    D --> E[(远程存储)]
    
    F[CLI 命令] --> C
    G[微调模块] --> C

核心组件

Files 资源类

Files 资源类封装了所有与文件操作相关的 API 方法。资料来源：src/together/resources/files.py

文件类型定义

Together SDK 使用 FilePurpose 枚举定义文件的用途类别。资料来源：src/together/types/files.py

错误处理

文件管理模块定义了专门的异常类用于处理各类错误情况。资料来源：src/together/error.py

Python API 使用

初始化客户端

from together import Together

client = Together()

上传文件

使用 files.upload() 方法将本地文件上传至服务器：

response = client.files.upload(
    file="somedata.jsonl",
    purpose="fine-tunes"  # 可选，默认为 fine-tunes
)

上传时系统会自动进行文件格式校验。资料来源：README.md 和 src/together/utils/files.py

列出文件

获取账户下所有已上传文件的列表：

response = client.files.list()

返回结果包含每个文件的元数据信息，包括文件名、创建时间、文件大小等。

检索文件元数据

通过文件 ID 获取特定文件的详细信息：

response = client.files.retrieve(
    id="file-d0d318cb-b7d9-493a-bd70-1cfe089d3815"
)

获取文件内容

下载并读取已上传文件的实际内容：

content = client.files.retrieve_content(
    id="file-d0d318cb-b7d9-493a-bd70-1cfe089d3815"
)

删除文件

从服务器删除指定文件以释放存储空间：

client.files.delete(
    id="file-d0d318cb-b7d9-493a-bd70-1cfe089d3815"
)

CLI 命令行接口

Together SDK 提供了命令行工具用于文件管理操作。资料来源：src/together/cli/api/files.py

基本命令结构

together files <子命令>

查看帮助

together files --help

检查文件

在上传前验证本地文件格式是否正确：

together files check example.jsonl

上传文件

将本地文件上传至 Together 服务器：

together files upload example.jsonl

支持指定文件用途：

together files upload example.jsonl --purpose fine-tunes

列出文件

显示账户下所有已上传文件：

together files list

检索文件元数据

获取特定文件的详细信息：

together files retrieve file-6f50f9d1-5b95-416c-9040-0799b2b4b894

检索文件内容

下载并显示文件内容：

together files retrieve-content file-6f50f9d1-5b95-416c-9040-0799b2b4b894

删除文件

从服务器删除指定文件：

together files delete file-6f50f9d1-5b95-416c-9040-0799b2b4b894

文件格式校验

Together SDK 在文件上传前会进行严格的格式验证，确保数据符合微调要求。资料来源：src/together/utils/files.py

JSONL 格式验证

上传的文件必须符合 JSONL（JSON Lines）格式规范：

• 每行必须是有效的 JSON 对象
• 文件扩展名应为 .jsonl
• 支持单行或多行 JSON 格式

多模态内容验证

对于包含多模态内容的文件，系统会进行以下校验：

错误处理机制

校验失败时会抛出 InvalidFileFormatError 异常，包含以下详细信息：

• 错误发生的行号
• 错误类型标识
• 具体的错误描述

与微调模块的集成

文件管理模块与微调功能紧密集成，是进行模型微调的前置步骤。资料来源：src/together/resources/finetune.py

典型工作流程

graph TD
    A[准备训练数据] --> B[上传文件]
    B --> C[获取 file ID]
    C --> D[创建微调任务]
    D --> E[监控训练进度]
    E --> F[下载微调模型]

训练文件引用

在创建微调任务时，通过 training_file 参数引用已上传文件的 ID：

client.fine_tuning.create(
    training_file="file-xxxxx",
    model="meta-llama/Llama-4-Scout-17B-16E-Instruct"
)

配置与参数

客户端初始化参数

文件上传参数

最佳实践

数据准备

1. 文件格式：使用标准 JSONL 格式，每行一个 JSON 对象
2. 数据清洗：确保数据编码为 UTF-8，避免特殊字符问题
3. 文件大小：建议单个文件不超过 100MB

上传策略

1. 预校验：使用 check 参数在上传说进行格式验证
2. 分批处理：大量数据建议分批上传
3. 错误处理：捕获并处理 InvalidFileFormatError 异常

存储管理

1. 定期清理：删除已完成微调的临时文件
2. 命名规范：使用有意义的文件名便于识别
3. 记录追踪：保存 file ID 以便后续引用

相关资源

• 微调文档
• Together API 文档
• GitHub 仓库

概述

模型微调（Fine-Tuning）是 Together Python SDK 中用于自定义预训练语言模型行为的核心功能模块。通过微调，用户可以使用自己的数据集对 Together 平台上托管的预训练模型进行定制化训练，使其更好地适应特定任务场景，如特定领域的问答、代码生成、内容分类等。

Together SDK 提供了完整的微调工作流支持，涵盖从训练任务提交、检查点管理到模型部署的全生命周期管理。

Pitfall Log / 踩坑日志

项目：togethercomputer/together-python

摘要：发现 12 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:624113979 | https://github.com/togethercomputer/together-python | README/documentation is current enough for a first validation pass.

2. 运行坑 · 来源证据：v.1.5.31

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v.1.5.31
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ec69ff431b15448799cc64a826efd011 | https://github.com/togethercomputer/together-python/releases/tag/v.1.5.31 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 运行坑 · 来源证据：v.1.5.33

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v.1.5.33
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8246897bffc548df9673fe0c390cb514 | https://github.com/togethercomputer/together-python/releases/tag/v.1.5.33 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 运行坑 · 来源证据：v1.5.28

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.5.28
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7e7977d7006e43939b5ceb03d0efad33 | https://github.com/togethercomputer/together-python/releases/tag/v1.5.28 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 维护坑 · 来源证据：v.1.5.29

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v.1.5.29
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e91b0421f8fe42ac815a709d90dcca27 | https://github.com/togethercomputer/together-python/releases/tag/v.1.5.29 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 维护坑 · 来源证据：v1.5.27

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.5.27
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_569e5bacb3584ae794141c49af91c5db | https://github.com/togethercomputer/together-python/releases/tag/v1.5.27 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:624113979 | https://github.com/togethercomputer/together-python | last_activity_observed missing

8. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作: 下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:624113979 | https://github.com/togethercomputer/together-python | no_demo; severity=medium

9. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:624113979 | https://github.com/togethercomputer/together-python | no_demo; severity=medium

10. 安全/权限坑 · 来源证据：`LogProbs.top_logprobs` typed as `Dict` but API returns `List[Dict]`

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LogProbs.top_logprobs typed as Dict but API returns List[Dict]
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4b91e5a8164f4aa9910f3d9737f1995c | https://github.com/togethercomputer/together-python/issues/443 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作: issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:624113979 | https://github.com/togethercomputer/together-python | issue_or_pr_quality=unknown

12. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:624113979 | https://github.com/togethercomputer/together-python | release_recency=unknown