> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# 量化

> 选择精度格式和量化方法，并只路由到提供你测试过的那种精度的提供商。

发送 `provider.quantizations`，即可只把请求路由到以你测试过的精度提供该模型的提供商：

```json theme={null}
{
  "model": "meta/llama-3.3-70b-instruct",
  "messages": [{ "role": "user", "content": "Hello" }],
  "provider": {
    "quantizations": ["FP8"]
  }
}
```

## 量化改变了什么

量化用更小的数值类型存储模型权重。这样同一个模型需要的内存更少、推理更快，但输出质量会有一定损失。描述一个量化模型需要两点：**格式**（数值类型，例如 `FP8` 或 `INT4`）和**方法**（权重如何转换成该格式，例如 `AWQ` 或 `GPTQ`）。

位数每减半，权重所需的内存就减半。对于一个 70B 参数的模型，仅权重大约需要：

| 格式 | 每个权重的位数 | 70B 模型的权重大小 |
| - | - | - |
| `FP32` | 32 | 约 280 GB |
| `BF16`、`FP16` | 16 | 约 140 GB |
| `FP8`、`INT8` | 8 | 约 70 GB |
| `FP4`、`INT4` | 4 | 约 35 GB |

这些数字是简单计算（参数数量 × 每个权重的字节数）得出的，不包括激活值和 KV 缓存，而提供商同样需要为它们分配内存。

## 比较精度格式

精度格式是提供商存储模型权重所用的数值类型。精度越低，占用内存越少、推理越快，但输出质量受影响的风险也越高。

| 格式 | 典型用途 | 主要优势 | 主要风险 |
| - | - | - | - |
| `FP32` | 基准/全精度 | 数值稳定性最高 | 内存和计算成本最高 |
| `BF16` | 训练 + 高质量推理 | 质量好，效率比 FP32 更高 | 仍比 8 位/4 位更重 |
| `FP16` | 常见的推理/训练路径 | 速度和内存节省都不错 | 动态范围比 BF16 小 |
| `FP8` | 注重吞吐量的推理/训练 | 速度和内存收益大 | 在困难提示词上质量下降明显 |
| `FP4` | 激进的效率模式 | 密度极高、成本极低 | 输出质量下降的风险更高 |
| `INT8` | 支持广泛的推理量化 | 效率高，对质量的影响中等 | 某些模型存在校准/敏感性问题 |
| `INT4` | 对成本敏感的部署 | 内存极低、吞吐量高 | 质量和稳健性的取舍更大 |

### BF16 还是 FP16

两者都是 16 位。`BF16` 保留了更大的指数范围，因此更稳定；`FP16` 常见且快速，但在某些工作负载上不够稳定。当提供商提供 `BF16` 时，对质量要求高的流量选择它更稳妥。

### FP8 和 FP4

`FP8` 带来很大的效率提升，并在大多数任务上保持可用的质量。`FP4` 更进一步，但质量下降更频繁，尤其是在细致的推理、长上下文和严格的结构化输出上。

### INT8 和 INT4

整数格式为推理吞吐量和内存而设计。它们能保持多少质量取决于[量化方法](#compare-quantization-methods)、校准数据和模型架构。`INT8` 比 `INT4` 更容易安全地部署。

### 读懂模型的标签

提供商会把变体标记为 `bf16`、`fp16`、`fp8`、`int8`、`q4`、`4bit`、`8bit` 等。这些命名并不统一：`4bit` 可能指 `FP4`，也可能指 `INT4`。请查看提供商的文档以确认确切的变体。

## 比较量化方法

`INT4` 这样的格式是精度目标；`AWQ` 或 `GPTQ` 这样的方法是权重转换到该格式的方式。`AWQ INT4` 和 `GPTQ INT4` 以不同方式达到同一目标，因此表现可能差别很大。方法会影响保留多少准确度、哪些运行时可以提供该模型、内存布局和推理速度，以及是否需要校准数据。

| 方法类别 | 典型用途 | 说明 |
| - | - | - |
| `AWQ` | 保留对激活敏感的关键权重 | 常用于在实际推理中平衡质量和效率 |
| `GPTQ` | 以最小化误差为目标的训练后量化 | 常用于紧凑的本地推理变体 |
| `GGUF` | llama.cpp 生态使用的打包格式 | 常与不同的量化级别（`Q4`、`Q5` 等）结合使用 |
| `EXL2` | ExLlama 生态中的激进低位变体 | 注重高吞吐量，受架构/运行时限制 |

要针对你自己的工作负载比较各种方法：

1. 先选择运行时：选你能可靠部署的那个。
2. 只保留该运行时支持的方法类别。
3. 在同一精度目标下对多种方法进行基准测试。
4. 跟踪失败模式，而不只是平均基准分数：结构化输出的正确性、长上下文的忠实度、工具调用的可靠性、安全与审核行为，以及负载下的尾部延迟。

## 路由到某一种精度

`provider.quantizations` 筛选器检查的是每个提供商对该模型的具体报价，而不只是提供商名称：

* **匹配时忽略大小写、空格、`-` 和 `_`。** 不存在歧义的别名也能匹配：`bfloat16` 对应 `BF16`，`float16` 对应 `FP16`，`float8` 对应 `FP8`。`4bit` 这样的标签不会被视为 `FP4` 或 `INT4`。
* **没有量化元数据的报价永远不会匹配。**
* **不会回退到其他精度。** 如果没有匹配的报价，请求会失败并返回 `400 unsupported_model_or_endpoint`，原因为 `quantization_not_available`。错误会列出可用的精度，并在 `routing_diagnostics.quantization` 下说明哪些提供商被排除以及原因。
* 也可以用 `routing.quantizations` 代替 `provider.quantizations`。

## 选择精度

| 工作负载 | 起步选择 |
| - | - |
| 对质量要求高的推理 | `BF16` / `FP16` |
| 平衡成本和质量 | `FP8` / `INT8` |
| 高吞吐量、对成本敏感 | 经验证后使用 `INT4` / `FP4` |

你不需要所有场景都用同一种精度。客户支持和关键决策保留较高精度，高流量的分类或摘要则可以接受较低精度。

**1. 设定成功标准**

设定质量阈值（任务准确率、通过率、结构化输出有效性）、延迟和成本目标，以及你不能接受的失败模式。

**2. 测量高精度基准**

从 `BF16` 或 `FP16` 开始。记录输出质量、中位数和尾部延迟以及 token 成本。所有更低的精度都与这个基准比较。

**3. 一次降低一级**

接下来尝试 `FP8` 或 `INT8`。只有在需要额外的成本或吞吐量节省时，才转向 `FP4` 或 `INT4`。除非你已有证据表明最小的变体适合你的工作负载，否则不要直接跳到它。

**4. 用接近生产环境的提示词测试**

包括长提示词、多步推理、工具调用，以及来自支持工单的边缘情况。

**5. 发布并持续观察**

在你自己的客户端中保留一个备用模型或精度，以应对没有匹配报价的情况；发布后监控质量；当提供商的运行时或模型修订版本变化时重新测试。选定精度后，再在此基础上调整[推理参数](https://phaseo.app/docs/zh-Hans/v1/guides/inference-parameters.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.