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

# 模型管理

> 在管理面板中配置 LLM 提供商、模型和模型组。

FIM One 提供了一个功能完整的管理 UI，用于管理 LLM 提供商和模型。本指南涵盖如何添加提供商、配置单个模型、调整高级结构化输出设置，以及将模型组织成组以实现一键切换。

有关基于 ENV 的配置（无管理 UI），请参阅[环境变量](/configuration/environment-variables)。有关模型选择建议，请参阅[推荐模型](/configuration/models)。

## 架构：提供商、模型、模型组

FIM One 将 LLM 配置组织为三个层级：

| 层级      | 代表内容                                          | 示例                                          |
| ------- | --------------------------------------------- | ------------------------------------------- |
| **提供商** | 一组共享凭证（API 密钥 + 基础 URL）。一个提供商可以托管多个模型。        | "My OpenAI Account"、"Company Bedrock Relay" |
| **模型**  | 提供商下的单个模型。具有自己的显示名称、API 模型标识符和高级设置。           | "GPT-4o"、"Claude Sonnet 4.6"                |
| **模型组** | 一个命名预设，将模型分配给角色（通用 / 快速 / 推理）。激活一个组会同时切换所有角色。 | "Production (OpenAI)"、"Budget (DeepSeek)"   |

```
Provider: "My OpenAI Account"
  ├── Model: "GPT-4o"         (model_name: gpt-4o)
  ├── Model: "GPT-5 Nano"     (model_name: gpt-5-nano)
  └── Model: "o3"             (model_name: o3)

Provider: "Anthropic Direct"
  ├── Model: "Claude Sonnet"   (model_name: claude-sonnet-4-6)
  └── Model: "Claude Haiku"    (model_name: claude-haiku-4-5)

Group: "Production"
  ├── General → GPT-4o
  ├── Fast    → GPT-5 Nano
  └── Reasoning → o3
```

***

## 添加提供商

<Steps>
  <Step title="打开模型页面">
    导航到**管理员**（侧边栏）并选择**模型**选项卡。
  </Step>

  <Step title="点击添加提供商">
    在提供商部分的右上方区域点击**添加提供商**按钮。
  </Step>

  <Step title="选择预设或使用自定义端点">
    对话框显示常见提供商的预设按钮：**OpenAI**、**Anthropic (Claude)**、**Google Gemini**、**DeepSeek**、**Mistral AI** 和 **OpenAI Compatible**（自定义端点）。点击预设会自动填充提供商名称和基础 URL。

    如果您的提供商未列出（例如第三方中继、Ollama 或任何其他 OpenAI 兼容端点），请选择 **OpenAI Compatible**。
  </Step>

  <Step title="输入凭证">
    填写必需字段：

    * **提供商名称** -- 友好标签（例如"我的 OpenAI 账户"）。这仅供您参考。
    * **基础 URL** -- API 端点。预设会自动填充此字段。对于自定义端点，输入完整 URL（例如 Ollama 的 `http://localhost:11434/v1`）。
    * **API 密钥** -- 您的提供商的 API 密钥。对于本地模型（Ollama），输入任何非空字符串（例如 `ollama`）。
  </Step>

  <Step title="保存">
    点击**创建**。提供商出现在列表中，您可以在其下添加模型。
  </Step>
</Steps>

<Tip>
  您可以为同一服务创建多个提供商。例如，两个具有不同 API 密钥的"OpenAI"提供商用于单独的计费账户，或"Anthropic (Direct)"和"Anthropic (via Bedrock)"具有不同的基础 URL。
</Tip>

***

## 添加模型

<Steps>
  <Step title="展开提供商">
    在"模型"页面上，单击现有提供商旁边的 chevron 以展开它并查看其模型。
  </Step>

  <Step title="单击添加模型">
    单击展开的提供商下方显示的**添加模型**按钮。
  </Step>

  <Step title="输入模型详情">
    填写两个必填字段：

    * **显示名称** -- 在 UI 中显示的人类可读名称（例如"GPT-4o"、"Claude Sonnet"）。可以是任何你喜欢的名称。
    * **模型名称 (API)** -- 发送到 API 的确切模型标识符（例如 `gpt-4o`、`claude-sonnet-4-6`、`deepseek-chat`）。这必须与你的提供商期望的内容相匹配。
  </Step>

  <Step title="配置高级设置（可选）">
    单击**高级**切换以显示其他设置：最大输出令牌、上下文大小、温度、原生函数调用和 JSON 模式。有关每个设置的详细信息，请参阅下面的[高级设置](#advanced-settings)部分。
  </Step>

  <Step title="保存">
    单击**创建**。该模型出现在其提供商下方，现在可用于分配给模型组。
  </Step>
</Steps>

***

## 高级设置

每个模型都有高级设置，用于控制 FIM One 如何与提供商的 API 交互以进行结构化输出提取。这些设置位于模型创建/编辑对话框中的**高级**切换开关下。

### 原生函数调用

**设置名称：** 原生函数调用（存储为 `tool_choice_enabled`）

**默认值：** 开启

控制 FIM One 是否使用强制 `tool_choice` 进行结构化输出提取。这是结构化输出降级链中的第 1 级 -- 当模型支持时最可靠的方法。

**何时禁用：**

* 您的模型返回错误，如 `"tool_choice 'specified' is incompatible with thinking enabled"` -- 常见于始终启用思考的模型（DeepSeek R1、Kimi K2.5）
* 结构化输出请求持续缓慢，每次调用约有 10 秒的延迟，随后无论如何都会回退到 JSON Mode

**禁用时的效果：** FIM One 跳过第 1 级（原生函数调用），从第 2 级（JSON Mode）开始进行结构化输出。ReAct 智能体的工具调用完全不受影响 -- 它使用 `tool_choice="auto"`，适用于所有模型，无论此设置如何。

<Note>
  此设置仅影响用于结构化输出提取的**强制**工具选择（DAG 规划、模式注解）。它**不**影响 ReAct 智能体，后者使用 `tool_choice="auto"` 自由决定何时调用工具。
</Note>

有关技术详情，请参阅 [LLM 提供商兼容性 -- tool\_choice\_enabled](/architecture/llm-provider-guide#the-fix-tool_choice_enabled)。

### JSON 模式

**设置名称：** JSON 模式（存储为 `json_mode_enabled`）

**默认值：** 开启

控制 FIM One 是否使用 `response_format=json_object` 进行结构化输出。这是降级链中的第 2 级。

**何时禁用：**

* 您的提供商拒绝助手消息预填充 -- 主要是 AWS Bedrock 中继，会抛出 `"This model does not support assistant message prefill"`

**禁用时的效果：** FIM One 跳过第 2 级（JSON 模式）并降级到第 3 级（纯文本提取）。现代模型仅从提示指令就能生成有效的 JSON，因此通常不会有质量损失。

有关技术细节，请参阅 [LLM 提供商兼容性 -- json\_mode\_enabled](/architecture/llm-provider-guide#the-fix-json_mode_enabled)。

### Temperature

**默认值：** 0.7（如果未设置，则继承自全局设置）

控制模型输出的随机性。范围：0（确定性）到 2（高度创意）。

<Note>
  当为 Anthropic 模型启用推理/扩展思考时，系统会自动将温度强制设置为 1.0。您无需手动设置此项。
</Note>

### 最大输出令牌数

模型在单个响应中可以生成的最大令牌数。留空以使用系统默认值（64,000）。对于 VRAM 受限的本地模型，请明确设置为较低的值（例如 8192）。

### 上下文大小

模型的上下文窗口大小（以令牌为单位）。留空以使用系统默认值（128,000）。将其设置为与您的模型实际能力相匹配 -- 对于本地模型，这通常是 4K-32K，具体取决于模型和可用内存。

***

## 推荐配置

大多数模型使用默认设置（两个开关都打开）可以正常工作。仅在遇到错误或不必要的延迟时进行调整。

下表涵盖常见的提供商和模型。数据来自 UniAPI 功能标签，并根据 **2026-03-22** 的运行时行为进行了验证。模型功能变化频繁——如果遇到错误，请查阅您的提供商的最新文档。

### 快速规则

* **原生 FC 开启** 用于支持函数调用的模型（大多数现代模型）
* **原生 FC 关闭** 用于始终启用思考模式且拒绝强制 `tool_choice` 的模型
* **JSON 模式开启** 用于大多数模型（安全默认值）
* **JSON 模式关闭** 仅用于 AWS Bedrock 中继（前缀拒绝）

### 按提供商配置矩阵

**OpenAI**

| 模型             | 角色 | 上下文    | 最大输出 | 原生FC | JSON模式 | 备注                 |
| -------------- | -- | ------ | ---- | ---- | ------ | ------------------ |
| `gpt-5.4`      | 通用 | 1,050K | 128K | ON   | ON     | 函数调用 + 结构化输出 + 推理  |
| `gpt-5.4-mini` | 快速 | 400K   | 128K | ON   | ON     | 函数调用 + 结构化输出 + 推理  |
| `o3-pro`       | 推理 | 200K   | 100K | ON   | ON     | 推理模型；FC与自动禁用思考配合工作 |

**Anthropic (Claude)**

| 模型                  | 角色 | 上下文    | 最大输出 | 原生FC | JSON模式 | 备注                  |
| ------------------- | -- | ------ | ---- | ---- | ------ | ------------------- |
| `claude-sonnet-4-6` | 通用 | 1,000K | 64K  | ON   | ON     | 函数调用 + 推理；FC时思考自动禁用 |
| `claude-haiku-4-5`  | 快速 | 200K   | 64K  | ON   | ON     | 支持函数调用              |
| `claude-opus-4-6`   | 推理 | 1,000K | 128K | ON   | ON     | 函数调用 + 推理；FC时思考自动禁用 |

**Google Gemini**

| 模型                       | 角色 | 上下文    | 最大输出 | 原生FC | JSON模式 | 备注                                 |
| ------------------------ | -- | ------ | ---- | ---- | ------ | ---------------------------------- |
| `gemini-3.1-pro-preview` | 通用 | 1,048K | 65K  | ON   | ON     | 最新预览版；已弃用gemini-3-pro-preview的后继版本 |
| `gemini-2.5-pro`         | 快速 | 1,048K | 65K  | ON   | ON     | 稳定GA版本；生产就绪                        |
| `gemini-3.1-pro-preview` | 推理 | 1,048K | 65K  | ON   | ON     | 支持思考，可配置thinking\_level            |

**DeepSeek**

| 模型                  | 角色 | 上下文  | 最大输出 | 原生FC    | JSON模式 | 备注                               |
| ------------------- | -- | ---- | ---- | ------- | ------ | -------------------------------- |
| `deepseek-chat`     | 通用 | 128K | 8K   | ON      | ON     | V3.2非思考模式；支持FC + JSON模式          |
| `deepseek-chat`     | 快速 | 128K | 8K   | ON      | ON     | 与通用模型相同；仅存在两个官方API模型ID           |
| `deepseek-reasoner` | 推理 | 128K | 64K  | **OFF** | ON     | 思考始终开启；拒绝强制tool\_choice；64K包含CoT |

**xAI (Grok)**

| 模型                            | 角色 | 上下文    | 最大输出 | 原生FC | JSON模式 | 备注                             |
| ----------------------------- | -- | ------ | ---- | ---- | ------ | ------------------------------ |
| `grok-4-1-fast-non-reasoning` | 通用 | 2,000K | 30K  | ON   | ON     | 函数调用 + 结构化输出                   |
| `grok-3-mini-fast`            | 快速 | 131K   | 131K | ON   | ON     | 函数调用 + 结构化输出 + 推理；131K为共享上下文预算 |
| `grok-4-1-fast-reasoning`     | 推理 | 2,000K | 30K  | ON   | ON     | 函数调用 + 结构化输出 + 推理              |

**Qwen (阿里云)**

| 模型                  | 角色 | 上下文    | 最大输出 | 原生FC | JSON模式 | 备注                                |
| ------------------- | -- | ------ | ---- | ---- | ------ | --------------------------------- |
| `qwen3.5-plus`      | 通用 | 1,000K | 64K  | ON   | ON     | 函数调用 + 结构化输出                      |
| `qwen-turbo-latest` | 快速 | 1,000K | 16K  | ON   | ON     | 可能支持FC（UniAPI标签不完整）               |
| `qwq-plus`          | 推理 | 131K   | 16K  | ON   | ON     | 推理 + 函数调用；思考可通过enable\_thinking切换 |

**Zhipu (GLM)**

| 模型               | 角色 | 上下文  | 最大输出 | 原生FC    | JSON模式 | 备注                               |
| ---------------- | -- | ---- | ---- | ------- | ------ | -------------------------------- |
| `glm-4.7`        | 通用 | 200K | 65K  | **OFF** | ON     | 不支持强制tool\_choice（仅`auto`）；编码能力强 |
| `glm-4.7-flashx` | 快速 | 200K | 65K  | **OFF** | ON     | 高吞吐量变体；免费`glm-4.7-flash`也可用      |
| `glm-5`          | 推理 | 200K | 65K  | **OFF** | ON     | 745B MoE旗舰版；内置推理（无API切换）         |

**Moonshot (Kimi)**

| 模型                 | 角色 | 上下文  | 最大输出 | 原生FC    | JSON模式 | 备注                             |
| ------------------ | -- | ---- | ---- | ------- | ------ | ------------------------------ |
| `kimi-k2.5`        | 通用 | 262K | 65K  | **OFF** | ON     | FC可用但思考开启时（默认）拒绝强制tool\_choice |
| `kimi-k2`          | 快速 | 131K | 32K  | ON      | ON     | 非思考模式；原生FC可用（生产环境已验证）          |
| `kimi-k2-thinking` | 推理 | 131K | --   | **OFF** | ON     | 思考始终开启；拒绝强制tool\_choice        |

**MiniMax**

| 模型                       | 角色     | 上下文  | 最大输出 | 原生FC | JSON模式 | 备注                                |
| ------------------------ | ------ | ---- | ---- | ---- | ------ | --------------------------------- |
| `MiniMax-M2.7`           | 通用     | 205K | 131K | ON   | ON     | 最新版本（2026年3月）；函数调用 + 结构化输出        |
| `MiniMax-M2.5`           | 快速     | 197K | 65K  | ON   | ON     | 函数调用 + 结构化输出；缓存读取更便宜（\$0.03/MTok） |
| `MiniMax-M2.7-highspeed` | 快速（速度） | 205K | 131K | ON   | ON     | 2倍吞吐量（\~100 tok/s），2倍成本           |
| `MiniMax-M2.5-highspeed` | 快速（速度） | 197K | 65K  | ON   | ON     | 2倍吞吐量（\~100 tok/s），2倍成本           |

**ByteDance (抖音)**

| 模型                    | 角色 | 上下文  | 最大输出 | 原生FC | JSON模式 | 备注                                            |
| --------------------- | -- | ---- | ---- | ---- | ------ | --------------------------------------------- |
| `doubao-seed-2-0-pro` | 通用 | 256K | 128K | ON   | ON     | 函数调用 + 结构化输出 + 推理                             |
| `doubao-seed-1-6`     | 快速 | 256K | 16K  | ON   | ON     | 函数调用 + 结构化输出 + 推理                             |
| `doubao-seed-1-6`     | 推理 | 256K | 16K  | ON   | ON     | 支持`reasoning_effort`（minimal/low/medium/high） |

**Meta (Llama)**

| 模型              | 角色 | 上下文  | 最大输出 | 原生FC | JSON模式 | 备注                                     |
| --------------- | -- | ---- | ---- | ---- | ------ | -------------------------------------- |
| `llama-3.3-70b` | 通用 | 131K | 16K  | ON   | ON     | FC + JSON模式取决于托管提供商；最大输出因提供商而异（2K–16K） |

<Note>
  **最大输出中的"--"** 表示提供商未报告限制。实际上，这些模型通常支持4K-16K输出令牌。如需特定值，请在模型的高级设置中明确设置**最大输出令牌**。
</Note>

<Tip>
  **诊断方法：** 检查应用程序日志中的`structured_llm_call: native_fc call raised`警告。如果看到这些警告后跟成功的JSON模式提取，则该模型不受益于原生函数调用。为该模型禁用**原生函数调用**以消除浪费的API调用和每个结构化输出请求约10秒的延迟惩罚。
</Tip>

<Warning>
  模型功能随着提供商API更新而频繁变化。上述建议基于**2026-03-26**的数据（UniAPI能力标签 + 生产运行时验证）。如果之前可用的模型开始返回错误，请检查提供商的更新日志以了解破坏性变更。
</Warning>

***

## 模型组

模型组允许您将模型分配给特定角色，并通过单击切换配置。

### 角色

FIM One 使用三个模型角色。每个角色在执行管道中服务于不同的目的：

| 角色            | 用途                                                    | 建议                                                             |
| ------------- | ----------------------------------------------------- | -------------------------------------------------------------- |
| **General**   | 规划、分析、ReAct 智能体、DAG 步骤执行（默认）                          | 您最强大的模型（例如，`gpt-4o`、`claude-sonnet-4-6`）                       |
| **Fast**      | `model_hint="fast"` DAG 步骤、上下文压缩、历史摘要                 | 针对速度和成本优化（例如，`gpt-5-nano`、`deepseek-chat`）。如果未分配，则回退到 General。 |
| **Reasoning** | `model_hint="reasoning"` DAG 步骤、领域升级的 ReAct（法律/医疗/金融） | 强大的推理模型（例如，`o3`、`deepseek-reasoner`）。如果未分配，则回退到 General。       |

### 创建模型组

<Steps>
  <Step title="打开Groups部分">
    在**Admin > Models**页面上，滚动到**Model Groups**部分。
  </Step>

  <Step title="点击Add Group">
    点击**Add Group**按钮。
  </Step>

  <Step title="为组命名">
    输入一个描述性名称（例如，"Production (OpenAI)"、"Budget (DeepSeek)"、"Local Dev"）。
  </Step>

  <Step title="为角色分配模型">
    对于每个角色（General、Fast、Reasoning），从下拉菜单中选择一个模型。下拉菜单显示来自活跃提供商的所有活跃模型，按提供商名称分组。您可以将某个角色保留为未分配状态——它将回退到General模型（或如果General也未分配，则回退到ENV配置的模型）。
  </Step>

  <Step title="保存">
    点击**Create**。该组现在可用于激活。
  </Step>
</Steps>

### 激活一个组

要激活一个模型组，请使用"模型"页面上的下拉菜单或激活控制。一次只能激活一个组。激活一个组会立即将其模型分配应用到所有新对话。

要停用当前组（回退到 ENV 配置的模型），请选择停用选项。

<Warning>
  切换活跃的模型组会影响**所有新对话**系统范围内。正在进行的现有对话将继续使用启动时处于活跃状态的模型。
</Warning>

***

## 领域感知模型升级

当自动路由器检测到专业领域 — **法律**、**医疗** 或 **财务** — 系统会自动将模型选择升级到超出常规角色分配的范围：

* **ReAct 模式：** 通用模型被替换为**推理模型**（`registry.get_by_role("reasoning")`）。这意味着模型组中的推理槽不仅用于 DAG `model_hint="reasoning"` 步骤 — 它还充当领域特定 ReAct 任务的升级目标。
* **DAG 模式：** 领域上下文被注入到规划器提示中，指导它为需要专家级准确性的步骤分配 `model_hint="reasoning"`。

此升级是自动的，除了在活跃模型组中分配推理模型（或通过 `REASONING_LLM_MODEL` 环境变量）外，不需要任何配置。

**相关环境变量：**

| 变量                                  | 默认值    | 描述                                                    |
| ----------------------------------- | ------ | ----------------------------------------------------- |
| `DAG_CITATION_VERIFICATION`         | `true` | 为法律/医疗/财务内容启用步骤后引用验证。通过正则表达式提取引用，并通过 LLM 判断验证准确性。     |
| `DAG_STRUCTURED_CONTEXT_MULTIPLIER` | `3.0`  | DAG 依赖上下文中结构化内容（引用、表格、代码块）的截断预算乘数。较高的值可保留步骤间更多的结构化数据。 |

<Tip>
  如果您的工作负载涉及法律、医疗或财务查询，请确保您的推理模型是强大的推理器（例如 `o3`、`claude-opus-4-6`、`deepseek-reasoner`）。自动升级依赖于此槽位由能够处理领域关键准确性要求的模型填充。
</Tip>

## ENV 回退

当没有管理员配置的模型组处于活跃状态时，FIM One 会回退到基于 ENV 的配置：

| 角色        | ENV 变量                                 |
| --------- | -------------------------------------- |
| General   | `LLM_MODEL`                            |
| Fast      | `FAST_LLM_MODEL`（回退到 `LLM_MODEL`）      |
| Reasoning | `REASONING_LLM_MODEL`（回退到 `LLM_MODEL`） |

管理员配置的模型始终优先于 ENV 变量。系统健康检查会考虑两个来源 -- 只要配置了活跃的模型组或有效的 ENV 变量，LLM 子系统就会报告为健康状态。

有关完整的 ENV 参考，请参阅[环境变量](/configuration/environment-variables#llm-required)。

## 导出和导入

模型页面支持将整个提供商和模型配置（提供商、模型和组）导出为 JSON 文件，并在另一个实例上导入。这对以下情况很有用：

* 在开发、测试和生产环境之间迁移配置
* 与团队成员共享已知的良好模型设置
* 在进行更改前备份配置

<Warning>
  导出的配置**不**包括 API 密钥。导入后，您必须编辑每个提供商以输入相应的 API 密钥。
</Warning>