# 将 LLM 模型添加到 GitHub Copilot CLI

在Copilot CLI中使用您首选的远程或本地模型。

可通过多种方式将模型添加到 Copilot CLI 中。

* **Ollama**：Copilot CLI 会自动发现你计算机上运行的 Ollama 提供的模型，你可以从模型选取器中添加这些模型。
* **手动配置的模型提供程序**：通过在配置文件中指定自己的凭据来添加外部模型提供程序。 此方法通常称为客户自带密钥（BYOK）。
* **在本地安装MAI Code 1.1 Flash**：满足所需系统要求的 Windows 用户可以直接从模型选取器安装此模型，并在本地计算机上运行它。

> [!NOTE]
> 本文介绍如何配置自定义模型供自己使用。 若要为组织或企业中的用户设置自定义模型，请参阅 [在你的组织中为 GitHub Copilot 启用自定义模型](/zh/copilot/how-tos/administer-copilot/manage-for-organization/enable-custom-models) 和 [在企业中为 GitHub Copilot 启用自定义模型](/zh/copilot/how-tos/administer-copilot/manage-for-enterprise/enable-custom-models)。

## 模型要求

选择支持 **工具调用** （也称为函数调用）和 **流式传输**的模型和终结点。 这些功能允许 Copilot CLI 使用工具，并实时显示陆续到达的响应。

配置令牌限制以匹配模型，尤其是对于较小的本地模型。 对于未知模型，Copilot CLI 的提示令牌默认上限可为 128,000 个，这可能超过模型的实际容量。 设置更高的限制不会增加模型的上下文窗口。

## 从 Ollama 添加模型

如果 Ollama 在本地计算机上运行，并且你已经下载了一个模型， Copilot CLI 则可以发现模型，并允许你从模型选取器中添加它。

### 先决条件

您必须已在本地计算机上安装 Ollama，并已下载至少一个模型。 有关详细信息，请参阅 Ollama 网站上的[下载 Ollama 页面](https://ollama.com/download)。

### 添加模型

1. 在交互式会话中，输入 `/model`。

2. 在“本地和自承载”下查找 Ollama 提供的模型。

   已从 Ollama 下载但尚未添加的任何模型会显示状态为“已发现”。

3. 选择发现的模型，然后按 <kbd>Enter</kbd>。

4. 选择 **“添加并用于此次会话”** 以切换到该模型，或选择 **“添加但不切换”** 以继续使用当前模型。

5. 按 <kbd>Esc</kbd> 退出选取器。

CLI 将模型详细信息保存到 `providers.json` 文件，以便在以后的会话中可用。

> [!NOTE]
> Copilot 默认情况下在 `http://127.0.0.1:11434` 检查 Ollama。 如果 Ollama 使用其他本地地址或端口，请在启动 CLI 之前设置 `OLLAMA_HOST`。 自动发现仅检查本机上的地址。 对于另一台计算机上的 Ollama 服务器，请改用提供程序配置文件。

## 手动添加模型提供程序配置

若要使用除 Ollama 以外的模型提供程序，需要手动将提供程序详细信息添加到 `providers.json` 文件。

### 先决条件

必须具有 API 密钥才能添加需要身份验证的模型提供程序。

### 支持的提供程序

若要连接到模型提供程序的 API，可以使用以下提供程序类型：

| 供应商类型       | 兼容的服务                                                                       |
| ----------- | --------------------------------------------------------------------------- |
| `openai`    | OpenAI 以及具有与 OpenAI 兼容的 API 的服务，例如 Ollama、vLLM 和 Foundry Local。 这是默认提供程序类型。 |
| `azure`     | Azure OpenAI 服务。                                                            |
| `anthropic` | Anthropic（克劳德模型）。                                                           |

### 添加提供程序和模型

`providers.json` 文件存储已配置提供程序和模型的详细信息。 它位于你的 CLI 配置目录中，通常为 `~/.copilot`。 在启动 CLI 之前，可以通过将 `COPILOT_PROVIDERS_CONFIG` 设置为另一个文件的路径来使用另一个文件。

在 `providers.json` 文件中配置的模型在 CLI 的模型选取器中可用，以及你的帐户可用的由 GitHub 提供的模型。

> [!IMPORTANT]
> 在此文件中输入的凭据以纯文本形式存储。 将文件保密，不将其提交到存储库或分享它。 JSON 中像 `$MY_API_KEY` 这样的值会被视为字面文本，而不是从您的环境中读取。

1. 打开 `providers.json`，或创建它（如果不存在）。 添加提供商和模型。 例如，此配置添加 OpenAI 模型提供程序和一个模型：

   ```json
   {
      "providers": [
         {
            "name": "my-provider",
            "type": "openai",
            "baseUrl": "https://api.openai.com/v1",
            "apiKey": "YOUR-API-KEY"
         }
      ],
      "models": [
         {
            "id": "YOUR-MODEL-NAME",
            "provider": "my-provider"
         }
      ]
   }
   ```

   将 `YOUR-API-KEY` 替换为您的提供商的 API 密钥，并将 `YOUR-MODEL-NAME` 替换为您的帐户可用的模型名称。 对于另一个与 OpenAI 兼容的提供程序，请将 `baseUrl` 更改为其 API URL。 如果提供程序不需要身份验证，则省略 `apiKey` 。

   如果文件已包含提供程序和模型，请添加到现有数据中，而不是替换现有数据。

   对于需要其他设置的提供程序或模型：

   * 将提供程序的`type`设置为 Azure OpenAI 的`azure`或 Anthropic 的`anthropic`，并使用该提供程序的 API URL 和凭据。
   * 对于使用响应 API 的 OpenAI 或 Azure 模型，请向提供程序添加 `"wireApi": "responses"`。 默认值为 `completions`。
   * 对于 Azure 部署，请将模型的`wireModel`设置为部署名称，并将`modelId`设置为所部署模型的名称。 如果需要特定的 API 版本，请向提供程序添加 `"azure": { "apiVersion": "YOUR-API-VERSION" }`。 将 `YOUR-API-VERSION` 替换为终结点所需的版本。
   * 如果模型 `id` 是你选择的名称，而不是提供程序接受的名称，则将 `wireModel` 设置为提供程序的模型名称。 将 `modelId` 设置为 CLI 识别的模型名称，以便可以使用该模型的功能和限制。
   * 在模型上设置 `maxPromptTokens` 和 `maxOutputTokens`，以符合其支持的上限。 使用大于零的整数。
   * 若要使用持有者令牌而不是 API 密钥进行身份验证，请在提供程序上设置 `bearerToken` 。

   可以在此文件中配置许多其他参数。 有关详细信息，请参阅“[GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#providersjson)”。

2. 若要从同一提供程序中添加另一个模型，请将另一个条目添加到 `models` 中，该条目具有不同的 `id` 项和相同的 `provider`。

   > [!NOTE]
   > 每个模型的`provider`值必须与提供程序的`name`匹配。

3. 若要添加其他提供程序，请向`name`添加一个具有唯一`providers`的条目，然后添加其模型。

4. 保存文件并重启 CLI。

5. 若要在启动会话时选择示例模型，请运行：

   ```shell
   copilot --model PROVIDER-NAME/MODEL-NAME
   ```

6. 若要在会话期间切换模型，请使用 `/model` 斜杠命令。 有关详细信息，请参阅“[在  中选择模型](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/choose-a-model)”。

7. 若要停止从已保存的配置加载提供程序，请从 `providers` 中删除其条目，并从 `models` 中删除其模型条目，然后重启 CLI。 在删除当前默认模型之前，请先选择其他默认模型 `/model --global`。

## 从模型选取器安装本地模型

> [!NOTE]
> 此功能处于 公开预览 阶段，并且可能会发生变化。 若要使用此功能，请使用 `--experimental` 选项启动 CLI，或在交互式会话中使用 `/experimental on`，为当前和将来的会话启用此功能和其他实验性功能。

如果使用Windows，并且计算机满足以下先决条件，则可以使用 CLI 的模型选取器在本地设备上安装和运行以下模型：

* MAI Code 1.1 Flash
* Flint NVFP4

### Prerequisites

您必须具备：

* Windows电脑

* 需要 NVIDIA GPU（不支持 AMD）

* 每个模型的最低可用总 RAM：

  * **MAI Code 1.1 Flash：**  96 GB
  * **Flint NVFP4：**  48 GB

* 每个模型的最低可用存储空间：

  * **MAI Code 1.1 Flash：**  60 GB
  * **Flint NVFP4：**  23 GB

* 已安装 llama.cpp v0.7.0 或更高版本，并将 `LLAMACPP_SERVER_PATH` 设置为其安装路径。 所需的构建版本：

  * **MAI Code 1.1 Flash：** [b11669](https://github.com/ggml-org/llama.cpp/releases/tag/b11669?utm_source=local-model-prereq-mai-code\&utm_medium=docs\&utm_campaign=universe-2026) 或更高版本
  * **Flint NVFP4：** [b11803](https://github.com/ggml-org/llama.cpp/releases?q=flint\&expanded=true\&utm_source=local-model-prerequisite-flint\&utm_medium=docs\&utm_campaign=universe-2026#release-b11803) 或更高版本

  请参阅[安装Windows llama.cpp](#installing-llamacpp-for-windows)。

### 在本地使用 MAI Code 1.1 Flash 的好处

MAI Code 1.1 Flash是一种编码优化模型，可在Windows电脑上本地运行。 通过使用在本地运行的模型，即可离线使用 Copilot 并避免消耗 GitHub AI Credits。

安装 MAI Code 1.1 Flash后，可以从模型选取器中选择它，就像任何其他模型一样。 该模型也可用于 Copilot Fusion 的 Fusion Standard 工作量级别。 当你将模型选择设置为 **Copilot Fusion** 并使用 Fusion Standard 时，MAI Code 1.1 Flash 将被自动选中来处理适当的任务，为需要更多资源或更高性能的任务保留基于云的模型。

### 使用模型选取器安装本地模型

1. 在本地交互式会话中，输入 `/model`。

2. 在“本地和自承载”下查找支持的本地模型。

   状态显示为“需要下载”。

   > [!NOTE]
   > 如果本地计算机是满足 GPU 和内存要求的Windows电脑，则本地模型才可供下载。

3. 使用向下键选择本地模型，然后按 <kbd>Enter</kbd>。

   CLI 检查计算机是否满足安装要求。 请参阅本文前面列出的 [先决条件](#prerequisites) 。

4. 选择**下载并设置**以开始下载模型。

   下载正在进行时，可以继续使用其他模型。 下载完成后，CLI 会在对话输出中通知你。

### 使用本地模型

下载完成后，本地模型将可用于会话。

您可以：

* 从模型选取器中选择它，然后选择 **“选择此模型”**。 请参阅“[在  中选择模型](/zh/copilot/how-tos/copilot-cli/use-copilot-cli/choose-a-model#choosing-a-model)”。
* **MAI Code 1.1 Flash 仅：** 选择 **Copilot Fusion**，然后在模型选取器中选择 **Fusion Standard**，Copilot 将在适当时自动使用本地模型。
* 将其分配给custom agent，以便专注处理任务。 然后，可以提示 Copilot 将该自定义代理用于某个任务的一部分，同时让主会话继续使用云端的其他模型。 请参阅“[为 GitHub Copilot CLI 创建和使用自定义智能体](/zh/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli#delegating-focused-tasks-to-a-specific-model)”。

> [!IMPORTANT]
> 从模型选取器下载本地模型后，请不要无论是通过直接选择还是通过 Copilot Fusion，在不同Copilot界面（VS Code、Copilot CLI、Copilot app）的会话中同时使用它。 每个图面都会将该模型的一个独立实例加载到内存中，这很可能会导致本地计算机耗尽 RAM。

## 在脱机模式下运行

若要防止 Copilot CLI 联系 GitHub 的服务器（例如发送遥测数据），请在启动 CLI 之前将 `COPILOT_OFFLINE` 环境变量设置为 `true`。 对于完全网络隔离，模型提供程序还必须位于本地或同一隔离环境中。 请参阅“[对 GitHub Copilot CLI 进行身份验证](/zh/copilot/how-tos/copilot-cli/set-up-copilot-cli/authenticate-copilot-cli#offline-mode)”。

## Troubleshooting

* **缺少 Ollama 模型：** 检查 Ollama 是否正在运行并下载了模型。 打开 `/model`，然后按 <kbd>Ctrl</kbd>+<kbd>R</kbd> 以再次扫描。 对于另一台计算机上的服务器，请手动配置其 OpenAI 兼容的 API URL，包括 `/v1`。
* **缺少已保存的模型：** 检查其 `provider` 是否与某个提供程序的 `name` 匹配，然后重启 CLI。 如果添加发现的模型时出现保存警告，请按照警告提示修复文件或其权限。
* **环境设置不生效：** 检查是否 `COPILOT_PROVIDERS_CONFIG` 选择包含提供程序或模型的文件。 显式选择的文件优先于环境设置。 否则，活动环境配置的提供程序优先于默认值 `providers.json`。
* **请求失败：** 检查 API URL、凭据、模型名称和 API 选项。 对于 Azure OpenAI，请检查部署名称。 对于有关请求令牌数的错误，请设置适合模型的令牌限制。