> ## 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.

# 预设

> 为团队保存可复用的 Gateway 配置。

预设是可复用的配置，可帮助团队统一提示、模型偏好和路由默认值。预设在 Phaseo 控制台中管理，并可与团队共享。

## 快速入门

<Steps>
  <Step title="创建预设">
    打开**控制台 -> 设置 -> 预设**，创建一个易于识别的标识符，例如 `release-summary`。只添加应在调用方之间共享的默认值。
  </Step>

  <Step title="在请求中引用预设">
    让调用方专注于用户输入，由预设提供稳定的提示、参数和路由默认值。

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.phaseo.app/v1/responses \
        -H "Authorization: Bearer $PHASEO_API_KEY" \
        -H "Content-Type: application/json" \
      	  -d '{
      	    "model": "@release-summary",
      	    "input": "Generate a release summary for the last 24 hours."
      	  }'
      ```

      ```typescript TypeScript theme={null}
      import Phaseo from "@phaseo/sdk";

      const client = new Phaseo({ apiKey: process.env.PHASEO_API_KEY! });

      const response = await client.generateResponse({
      	  model: "@release-summary",
      	  input: "Generate a release summary for the last 24 hours.",
      });
      ```

      ```python Python theme={null}
      from phaseo import Phaseo

      client = Phaseo(api_key="YOUR_API_KEY")

      response = client.generate_response({
      	    "model": "@release-summary",
      	    "input": "Generate a release summary for the last 24 hours.",
      })
      ```
    </CodeGroup>
  </Step>

  <Step title="检查路由结果">
    在**Gateway -> 使用情况**中打开请求，确认哪些默认值已应用以及由哪个提供商处理。
  </Step>
</Steps>

## 预设可以包含什么

* 添加到每个请求开头的系统提示。
* 允许使用的模型或模型系列。
* 用于路由偏好的提供商允许列表或忽略列表。
* 默认参数，例如 temperature、top\_p、max\_tokens 等。
* 对受支持模型可选的推理默认值。

预设名称以 `@` 开头，便于识别。

只能通过请求中的 `model` 字段调用预设。Phaseo 不提供单独的 `preset` 请求字段。

* 私有预设和工作区预设使用 `@{slug}`，并在 API 密钥所属的工作区中解析。
* 公共预设使用 `@{username}/{slug}`，可在任意工作区中解析。例如 `@octavia/release-summary`。

公开发布需要启用公共资料并设置用户名。公共标识符冲突按发布者分别处理，因此两个发布者可使用相同的标识符而不会产生歧义。用户名全局唯一。标识符会转换为小写，支持字母、数字、连字符、下划线、句点和冒号。

## 版本和 Marketplace 分支

保存更改会更新私有草稿。准备好后，使用**发布新版本**；Phaseo 会创建不可变的编号版本，并保留所有旧版本供审核。

预设所有者可以选择版本标签的显示方式：

* **顺序编号：**`v1`、`v2`、`v3`。
* \*\*语义化版本：\*\*明确的 SemVer 标签，例如 `1.2.0`、`2.0.0-beta.1` 或 `1.4.2+build.7`。
* **日期版本：**`YYYY.MM.DD`；同一天发布多个版本时追加数字后缀，例如 `2026.08.02.2`。

Phaseo 在内部维护单独且单调递增的发布编号，因此无论公开标签格式如何，时间顺序、上游比较和派生关系都保持确定。

Marketplace 副本会固定到复制时的准确上游版本。发布者推出更新后，副本会显示更新通知。应用更新只会修改副本草稿，因此工作区所有者可以审核并明确发布，不会让上游作者直接改变生产行为。

Phaseo 会保留每个分支的直接来源和完整祖先链。因此，即使某个预设被多次复制和重新发布，Marketplace 页面也能区分直接分支和所有后代。

## 预设的合并方式

在 Gateway 上下文中使用预设解析请求时，预设会在提供商路由之前应用：

* 默认参数只填充请求正文中缺失的字段，不会覆盖调用方已提供的值。
* 如果请求已有系统消息，预设提示会添加到该消息前面。如果请求使用 Anthropic 风格的 `system` 字段，提示会添加到该字段前面。
* 提供商允许和忽略列表会在提供商选择之前应用，因此它们会缩小回退范围，而不是仅作为装饰标签。
* 使用预设模型允许列表之外模型的请求会尽早被拒绝，不会悄悄改路由到其他模型。

预设是公开支持可复用请求默认值和轻量兼容性转换的主要方式，无需每个调用方重复实现相同的提示或参数逻辑。

## 当前公开的预设功能

控制台中的预设流程有意限制为稳定且明确的一组请求配置：

* 系统提示注入
* 模型允许列表
* 提供商允许或忽略列表形式的路由限制
* 解码和生成默认值
* 推理默认值

如果需要更复杂的调用方专属转换，请将它们集中在一个应用边界层，并使用预设保存团队共享的默认值。

## 管理预设

在**控制台 -> 设置 -> 预设**中创建和管理预设。如果工作流在提示、路由或缓存行为方面差异明显，请使用不同的标识符。

## 何时使用预设

* 在多个服务之间统一系统提示。
* 为满足合规要求，将路由限制为获批提供商。
* 在不同环境之间保持默认参数一致。
* 为迁移项目提供持久位置来保存提示、路由和参数默认值，同时基本不改动应用代码。

## 相关指南

* [收集预设反馈](./preset-feedback.mdx)
* [路由与回退](./routing-and-fallbacks.mdx)
* [推理参数](./inference-parameters.mdx)
* [功能对等矩阵](../migration-guides/feature-parity-matrix.mdx)


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