> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/zh/si-you-ai/configuration.md).

# AI 配置

## 使用 AI - 一般步骤

1. [定义模型](#ai-model-management) 通过从包含的精选模型中选择，或上传受支持的 .gguf 格式模型
2. [配置助手](#ai-assistant-management) 基于已定义的模型，并针对特定用例或任务进行定制设置
3. [将内容上传到工作区](#add-files-to-the-workspace) 向助手提供包含相关内容的文件
4. 接入：
   * [OpenAI Router（常用方法）](/automate-protect-and-extend/zh/si-you-ai/open-ai-router.md)：通过内置引擎以编程方式连接到助手
   * [交互式聊天会话](/automate-protect-and-extend/zh/si-you-ai/chat-sessions.md)：在 VergeOS UI 中与助手交互（有助于测试）
   * **VergeOS API**：使用标准 VergeOS API 命令访问助手

## 通用 AI 设置

导航到 **AI** 在顶部菜单中，然后点击 **AI 设置** 以配置默认 AI 参数。

AI 设置页面允许你为 AI 组件配置全局默认值：

* **默认 AI 集群**：指定 AI 工作负载的默认计算集群。新的 AI 模型将默认部署到该集群。
* **聊天历史保留时长**：设置聊天会话历史的保留时间（以天为单位）。默认值为 60 天。

***

## AI 模型管理

AI 模型为你的 AI 助手和应用提供底层智能。VergeOS 通过支持标准的 \*.gguf 格式，兼容广泛的 AI 模型，允许用户下载并运行任何兼容文件。VergeOS UI 中还直接展示了若干精选模型，可快速部署。

### 安装 AI 模型

{% hint style="success" %}
**精选模型**

系统包含若干预配置模型，已使用默认设置配置，可自动下载
{% endhint %}

1. 导航到 **AI** > **模型**.
2. 选择 **点击安装** 在所需模型上，以安装可用的精选模型之一。 **-或-** 点击 ***新建模型*** 在左侧菜单中。
3. 配置所有所需设置：

* **模型选择**：从精选的基础模型列表中选择（例如，Llama-3.2、Phi-4-Instruct），并选择一个大小 **变体** （例如，小型 – 1GB）。 **-或-** 选择 --自定义-- 并提供一个 **URL** 以下载 .gguf 模型文件
* **名称**：为你的模型输入一个描述性的名称。
* **描述** （可选）：添加有关模型用途、配置或预期使用方式的详细信息。
* **核心数**：分配给每个模型实例的最大核心数。
  * 支持 GPU 的模型：核心分配影响很小。
  * 仅 CPU 或回退模式：核心分配对启动和性能至关重要。
  * 过度分配核心并不会提升性能；未使用的核心将保持空闲。
* **内存**：每个模型实例分配的内存：
  * 加载和运行模型需要一定的基础 RAM。实际需求因模型类型和大小而异。
  * 所需 RAM 基础量的一般指导：分配略多于模型文件大小的 RAM（例如，2GB 的模型可能需要 3GB RAM）。
  * 支持并发请求（即并行设置）和更大上下文窗口时，可能还需要额外的 RAM。
  * 先从较充裕的分配开始，然后通过模型仪表板监控实际使用情况。如果观察到的消耗明显低于分配量，可适当缩减以优化资源效率。
* **集群** （默认使用全局 AI 设置中定义的集群）：选择模型将运行的 VergeOS 集群。
* **HA 组**：指定模型的高可用组。同一 HA 组的成员将在可能的情况下运行在不同节点上。
* **GPU 资源组分配**：- 选择一个 GPU 资源组以分配 GPU 设备，或选择 *--仅 CPU--* 以仅在 CPU 上运行。

{% hint style="info" %}
**GPU 设备从称为** [**资源组**](/run-the-platform/zh/xi-tong-guan-li/device-pass-overview.md#resource-groups)**.**
{% endhint %}

* **当 GPU 资源不可用时允许 CPU 回退**：启用此选项可在 GPU 设备不可用时使用 CPU 资源。使用此选项时，请确保为回退场景分配足够的 CPU 核心。
* **首选层级**：选择用于托管模型的存储层级。
* **上下文大小** （默认 8192）：- 模型在活动会话中可处理的最大 token 数。这包括：
  * 用户输入
  * AI 输出
  * 系统提示
  * 对话历史

{% hint style="success" %}
**Token**

* 1 个 token ≈ 4 个字符（英语平均值）
* 1 个单词 ≈ 1.33 个 token
* 8192 个 token ≈ 2,000–4,000 个单词或约 12–20 页文本
  {% endhint %}

{% hint style="info" %}
**上下文大小注意事项**

* 连贯性：更长的上下文可提升跨对话或文档的连续性

* 准确性：更多上下文可实现更好的决策

* 性能：更大的上下文大小需要更多 RAM 和计算资源
  {% endhint %}

* **并发**：每个模型实例可处理的并发请求数量

* **最小工作器数**：模型启动时启动的模型实例最小数量。

* **最大工作器数**：为满足需求可启动的模型实例最大数量。

{% hint style="success" %}
**模型正在运行的模型实例（工作器）数量会显示在模型仪表板上，每个实例都表示为一个运行中的工作器。**
{% endhint %}

* **插入思考标签**：添加自定义标签，以区分链式思考推理和最终输出。某些模型会抑制此标签或将其视为非输出内容，以降低延迟。
* **从历史记录中移除思考标签**：启用后，将从响应历史记录中排除链式思考内容，只返回最终答案。

5. 点击 **提交** 以下载并配置指定模型。

{% hint style="success" %}
**模型下载可能需要几分钟甚至更久。模型仪表板（点击 *****模型***** 左侧菜单中的模型并双击该模型）在模型传输过程中会显示“Downloading”状态和进度。 *****状态***** 将在模型完全下载、初始化并准备就绪后变为“Online”。**
{% endhint %}

{% hint style="success" %}
**新助手**

当你创建新模型时，默认也会创建一个新助手。该 *新助手* 表单将显示出来，允许自定义新助手的默认设置。
{% endhint %}

## AI 助手管理

### 概述

AI 助手是经过配置的 AI 模型，可为你的 AI 功能提供特定能力和行为。它们可以通过特定提示词和设置进行自定义，以调整性能和响应类型。

### 创建助手

1. **开始创建新助手：** 在创建新模型时，会自动创建一个新助手，并使用默认设置，或使用在 *助手* 选项卡中所选的设置。也可以通过导航到 AI > 新助手来创建新助手。

* **名称**：输入助手的描述性名称。

{% hint style="success" %}
**当新助手自动创建时（伴随新模型创建），名称默认与模型名称相同。**
{% endhint %}

* **描述** （可选）：可输入更多详细信息来描述模型的配置、用途等。
* **模型**：从可用的基础模型中选择（例如，Llama-3.2、Phi-4-Instruct）。当助手随新模型创建而自动创建时，此字段会自动设置为关联模型且不可编辑。
* **设置配置**
* **聊天历史**：配置对话保留（仅交互式聊天会话）
  * ***默认开启*** - 聊天历史在会话开始时自动启用，但可以禁用
  * ***默认关闭*** - 聊天历史在会话开始时自动禁用，但可以启用
  * ***始终开启*** - 聊天历史始终启用；无法禁用
  * ***始终关闭*** - 聊天历史始终禁用；无法启用

{% hint style="success" %}
**每次开始新的聊天会话时，还可以选择删除上一会话的聊天历史。**
{% endhint %}

* **禁用思考**：启用或禁用多步推理。启用时，AI 会“展示其思考过程”以提高准确性；这对复杂逻辑、数学、调试或战略规划尤其有用。禁用思考可获得更快的响应并降低资源使用，但可能会降低精确度。

{% hint style="info" %}
**以下 *****思考***** 功能的可用性取决于模型支持。**
{% endhint %}

* **系统提示词**：为 AI 的行为、语气和任务导向设定基础指令。此提示会影响模型如何解释上下文并生成响应。精确性很重要；含糊或信息过载的提示词会降低输出质量。系统提示指令会 **在每次聊天交互中提供给模型**.

{% hint style="info" %}
**系统提示注意事项**

* 更长的提示词可以提高响应准确性和任务一致性，但也会增加资源使用。

* 完整的系统提示会在每次查询时重新处理，并计入模型的总输入 token 数（上下文长度），这可能会限制用户输入和先前对话可用的空间。
  {% endhint %}

* **温度**：控制生成响应的创造性和随机性。（0.0 = 确定性，1.0 = 创造性），例如：0.2 表示措辞紧凑、一致；0.75 表示隐喻、幽默、意想不到的角度 一般指导：
  * 低温度（例如 0.0–0.3）- 确定性、聚焦且可重复的答案；适用于技术文档、合规指导、客户支持等场景
  * 高温度（例如 0.7–1.0）- 富有创意、探索性更强、可预测性更低的响应；适用于头脑风暴、设计构思、面向特定受众的措辞
  * 中温度（例如 0.4–0.6）- 响应在结构和变化之间取得平衡，不如低温度那样正式和机械；非常适合场景规划、UI/UX 分析或基础设施权衡

* **上下文评分**： （默认 65）用于确定模型如何评估某条信息在给定上下文窗口中的相关性、实用性或显著性。此值设置某段上下文被视为适用所需的最低分数。它有助于决定关注什么、忽略或压缩什么、在多轮中保留什么等。
  * 0 会将任何内容视为匹配，而 100 则要求严格的完全匹配
  * 最佳上下文评分取决于所用模型、上下文信息（例如上传到助手工作区的文档）以及使用场景。
  * 默认上下文评分（65）提供了中等程度的相关性，既不过于精确，也不完全偏离主题。如果不确定你的使用场景的最佳设置，请先使用默认设置，运行测试场景评估输出，然后在需要时调整上下文评分。

* **最大 Token 数**： （默认：0 = 不限制）以 token 为单位设置系统响应的最大长度。不同 AI 模型之间的 token 各不相同，但通常 1 个 token 约等于 0.7 个单词。
  * 设置最大 token 时，应小于模型的上下文大小
  * 对于许多用例，建议设置最大 token 以限制响应长度（并避免过于冗长）
  * 不同模型的标准或默认响应各不相同，有些模型倾向于给出非常冗长的回应，而另一些则默认提供更简短精炼的答案。

* **高级**：该字段保留用于未来增强配置选项。如果你需要 UI 中未提供的其他 AI 设置，请联系支持。

2. 点击 **提交** 以创建/保存助手配置。助手将被部署并可供使用。

***

## 管理 AI 文件内容

助手工作区允许你上传和管理文件，为助手提供专有的上下文知识库。

**要访问助手工作区**:

* 导航到助手仪表板（AI > 点击所需模型。）
* 点击 **查看工作区** 在左侧菜单中。

## 向工作区添加文件

* 点击 **上传** 在左侧菜单中，然后点击 **“选择文件”** 按钮。
* **浏览并选择** 所需文件。
* 点击 **打开** 以将所选文件添加到上传队列。
* 可选地，可为每个文件配置描述和首选层级。
* 点击 **开始** 以开始上传过程。

{% hint style="info" %}
**请勿重新加载或关闭浏览器窗口**

弹出消息将显示上传队列、文件大小以及每个文件的上传进度。请在所有上传完成之前不要重新加载或关闭浏览器页面，以确保文件完整传输。
{% endhint %}

## 修改工作区文件

在列表中选择一个文件并点击 **编辑** 左侧菜单中的相应项，以修改名称、描述和/或首选层级。

### 移除工作区文件

* 选择所需文件并点击 **删除** 在左侧菜单中。
* 点击 **是** 以确认删除操作。

***

## 故障排除

### 常见问题

#### 模型安装失败

* **资源不足**：确保 CPU、RAM 和存储充足
* **网络连接**：验证模型下载的网络访问
* **权限问题**：检查用户对模型管理的权限

#### 性能问题

* **响应缓慢**：增加 CPU 分配或启用 GPU 加速
* **内存错误**：增加 RAM 分配或启用内存映射
* **资源争用**：监控资源使用情况并调整分配

### 诊断步骤

1. **检查系统资源**：验证可用的 CPU、RAM 和存储
2. **查看日志**：检查系统日志中的错误消息
3. **网络连接**：测试网络访问和配置
4. **权限验证**：确认用户权限和访问权限
5. **模型状态**：检查模型安装和部署状态

***

**版本兼容性**：此功能适用于 VergeOS 26.0 及更高版本。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/automate-protect-and-extend/zh/si-you-ai/configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.