Select language: current language is Simplified Chinese
搜索或询问 Copilot
打开菜单
Open Sidebar

自带密钥（BYOK）

使用来自不同模型提供商的 API 密钥与 Copilot SDK，绕过 GitHub Copilot 身份验证。

谁可以使用此功能？

GitHub Copilot SDK 适用于所有 Copilot 计划。

在本文中

注意

          Copilot SDK 当前处于 公共预览版. 功能和可用性可能会发生更改。

通过自带密钥（BYOK），您可以使用来自模型提供商的 Copilot SDK 自己的 API 密钥，从而绕过 GitHub Copilot 验证。 这对于企业部署、自定义模型托管或需要与模型提供商直接计费时非常有用。

支持的提供程序

Provider类型值备注
OpenAI"openai"OpenAI API 和 OpenAI 兼容的端点
Azure OpenAI / Azure AI Foundry
          `"azure"` 或 `"openai"` | Azure 托管的模型（请参阅 [Azure 终结点类型](#azure-endpoint-type-confusion)） |

| Anthropic | "anthropic" | Claude 模型 | | Ollama | "openai" | 通过 OpenAI 兼容 API 使用的本地模型 | | Microsoft Foundry Local | "openai" | 通过 OpenAI 兼容的 API 在本地设备上运行 AI 模型 | | 其他与 OpenAI 兼容的 | "openai" | vLLM、LiteLLM 和类似 |

快速入门：Azure AI Foundry

Azure AI Foundry（前 Azure OpenAI）是企业常见的 BYOK 部署目标。 以下示例显示了完整的 Node.js/TypeScript 设置：

  1. 使用 Azure AI Foundry 终结点和 API 密钥创建会话：

    TypeScript
    import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({
    model: "YOUR-DEPLOYMENT-NAME",
    provider: {
        type: "openai",
        baseUrl: "https://YOUR-RESOURCE.openai.azure.com/openai/v1/",
        wireApi: "responses",  // Use "completions" for older models
        apiKey: process.env.FOUNDRY_API_KEY,
    },
});

session.on("assistant.message", (event) => {
    console.log(event.data.content);
});

await session.sendAndWait({ prompt: "What is 2+2?" });
await client.stop();

用您的 Azure 资源名称替换YOUR-RESOURCE，用您的模型部署名称替换YOUR-DEPLOYMENT-NAME。 将 FOUNDRY_API_KEY 环境变量设置为 Azure API 密钥。

有关 Python、Go 和 .NET 中的示例，请参阅存储库中的 github/copilot-sdk。 有关 Java，请参阅 github/copilot-sdk-java 存储库。

提供程序配置参考

ProviderConfig 字段

领域类型说明
type
          `"openai"`
          \|
          `"azure"`
          \|
          `"anthropic"`
         | 提供者类型。 默认为 `"openai"`。 |

| baseUrl | 字符串 | 必填。 API 终结点 URL。 | | apiKey | 字符串 | API 密钥。 对于本地提供商（如 Ollama）可选。 | | bearerToken | 字符串 | 持有者令牌身份验证。 优先于 apiKey. | | wireApi | "completions" | "responses" | API 格式。 默认为 "completions"。 | | azure.apiVersion | 字符串 | Azure API 版本。 默认为 "2024-10-21"。 |

线路 API 格式

此设置 wireApi 确定要使用的 OpenAI API 格式：

  •         **
        `"completions"`
        ** （默认值）：聊天完成 API （`/chat/completions`）。 用于大多数模型。

  •         **
        `"responses"`
        **：响应 API。 用于支持较新的响应格式的 GPT-5 系列模型。

类型特定的注释

          **OpenAI （`type: "openai"`）**

  • 适用于 OpenAI API 和任何与 OpenAI 兼容的终结点。

  •         `baseUrl` 应包含完整路径，例如 `https://api.openai.com/v1`。

        **Azure （`type: "azure"`）**

  • 用于原生 Azure OpenAI 终结点。

  •         `baseUrl` 应只是主机，例如 `https://YOUR-RESOURCE.openai.azure.com`。

  • 不包括 /openai/v1 在 URL 中 - SDK 处理路径构造。

            **Anthropic（`type: "anthropic"`）**

  • 用于直接访问 Anthropic API。

  • 使用特定于 Claude 的 API 格式。

示例配置

OpenAI direct

TypeScript
provider: {
    type: "openai",
    baseUrl: "https://api.openai.com/v1",
    apiKey: process.env.OPENAI_API_KEY,
}

Azure OpenAI （本机 Azure 终结点）

在 type: "azure" 的终结点使用 *.openai.azure.com:

TypeScript
provider: {
    type: "azure",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com",  // Just the host
    apiKey: process.env.AZURE_OPENAI_KEY,
    azure: {
        apiVersion: "2024-10-21",
    },
}

用您的 Azure 资源名称替换 YOUR-RESOURCE。

Azure AI Foundry （OpenAI 兼容终结点）

对于具有 /openai/v1/ 终结点的 Azure AI Foundry 部署，请使用 type: "openai"：

TypeScript
provider: {
    type: "openai",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com/openai/v1/",
    apiKey: process.env.FOUNDRY_API_KEY,
    wireApi: "responses",  // For GPT-5 series models
}

奥拉马（本地）

TypeScript
provider: {
    type: "openai",
    baseUrl: "http://localhost:11434/v1",
    // No apiKey needed for local Ollama
}

Microsoft Foundry Local

          [Microsoft Foundry Local](https://foundrylocal.ai) 允许使用与 OpenAI 兼容的 API 在本地运行 AI 模型。 通过 Foundry Local CLI 安装它，然后将 SDK 指向本地终结点：
TypeScript
provider: {
    type: "openai",
    baseUrl: "http://localhost:YOUR-PORT/v1",
    // No apiKey needed for local Foundry Local
}

注意

Foundry Local 在未修复的动态端口上启动。 运行 foundry service status 以确认服务当前正在侦听的端口，然后在你的 baseUrl端口中使用该端口。

若要开始使用 Foundry Local：

Bash
# Windows: Install Foundry Local CLI (requires winget)
winget install Microsoft.FoundryLocal

# List available models
foundry model list

# Run a model (starts the local server automatically)
foundry model run phi-4-mini

# Check the port the service is running on
foundry service status

有关 macOS/Linux 安装，请参阅 foundrylocal.ai。

Anthropic

TypeScript
provider: {
    type: "anthropic",
    baseUrl: "https://api.anthropic.com",
    apiKey: process.env.ANTHROPIC_API_KEY,
}

持有者令牌身份验证

某些提供程序需要持有者令牌身份验证，而不是 API 密钥：

TypeScript
provider: {
    type: "openai",
    baseUrl: "https://YOUR-CUSTOM-ENDPOINT.example.com/v1",
    bearerToken: process.env.MY_BEARER_TOKEN,  // Sets Authorization header
}

注意

该 bearerToken 选项仅接受静态令牌字符串。 SDK 不会自动刷新此令牌。 如果令牌过期，则请求将失败，你需要使用新的令牌创建新会话。

自定义模型列表

使用 BYOK 时，CLI 服务器可能不知道提供程序支持哪些模型。 可以在客户端级别提供自定义 onListModels 处理程序，以便 client.listModels() 以标准 ModelInfo 格式返回提供程序的模型：

TypeScript
import { CopilotClient } from "@github/copilot-sdk";
import type { ModelInfo } from "@github/copilot-sdk";

const client = new CopilotClient({
    onListModels: () => [
        {
            id: "my-custom-model",
            name: "My Custom Model",
            capabilities: {
                supports: { vision: false, reasoningEffort: false },
                limits: { max_context_window_tokens: 128000 },
            },
        },
    ],
});

结果在首次调用后缓存。 处理程序完全替换 CLI 的 models.list RPC 功能，不存在回滚到服务器的情况。

有关 Python、Go 和 .NET 中的示例，请参阅存储库中的 github/copilot-sdk。 有关 Java，请参阅 github/copilot-sdk-java 存储库。

局限性

标识限制

BYOK 身份验证仅使用静态凭据。 不支持以下标识提供者：

  • Microsoft Entra ID （Azure AD）- 不支持 Entra 托管标识或服务主体。
  • 第三方标识提供者 - 无 OIDC、SAML 或其他联合标识。
  • 托管标识 - 不支持 Azure 托管标识。

必须使用自己管理的 API 密钥或静态持有者令牌。

注意

虽然 Entra ID 确实颁发持有者令牌，但这些令牌是短生存期（通常是一小时），需要通过 Azure 标识 SDK 自动刷新。 该 bearerToken 选项仅接受静态字符串 - SDK 没有用于请求新令牌的回调机制。 对于需要 Entra 身份验证且需要长时间运行的工作负载，您需要实现自己的令牌刷新逻辑，并使用更新的令牌创建新会话。

功能限制

某些 Copilot 功能的行为方式可能与 BYOK 不同：

  •         **模型可用性**：只有提供商支持的模型可用。

  •         **速率限制**：受提供商的速率限制，而不是 Copilot's。

  •         **使用情况跟踪**：使用情况由提供商跟踪，而不是 GitHub。

  •         **高级请求**：不计入 Copilot 高级请求配额。

提供程序特定的限制

Provider局限性
Azure AI Foundry无 Entra ID 身份验证;必须使用 API 密钥。
Ollama无 API 密钥;仅限本地;模型支持各不相同。
Microsoft Foundry Local仅限本地;模型可用性取决于设备硬件;不需要 API 密钥。
OpenAI受 OpenAI 速率限制和配额的约束。

故障排除

“未指定模型”错误

使用 BYOK 时， model 参数是必需的：

// Error: model required with custom provider
const session = await client.createSession({
    provider: { type: "openai", baseUrl: "..." },
});

// Correct: model specified
const session = await client.createSession({
    model: "gpt-4",
    provider: { type: "openai", baseUrl: "..." },
});

Azure 终结点类型混淆

对于 Azure OpenAI 终结点（*.openai.azure.com），请确保使用正确的提供商类型：

// Wrong: using "openai" type with native Azure endpoint
provider: {
    type: "openai",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com",
}

// Correct: using "azure" type
provider: {
    type: "azure",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com",
}

如果 Azure AI Foundry 部署提供一个与 OpenAI 兼容的终结点路径（例如 /openai/v1/），请改用 type: "openai"。

// Correct: OpenAI-compatible Azure AI Foundry endpoint
provider: {
    type: "openai",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com/openai/v1/",
}

连接被拒绝 （Ollama）

确保 Ollama 正在运行并可访问：

Bash
# Check Ollama is running
curl http://localhost:11434/v1/models

# Start Ollama if not running
ollama serve

连接被拒绝（Foundry Local）

Foundry Local 使用可在重启之间更改的动态端口。 确认活动端口：

Bash
foundry service status

更新您的 baseUrl 以匹配输出中显示的端口。 如果服务未运行，请启动模型以启动它：

Bash
foundry model run phi-4-mini

身份验证失败

  1. 验证 API 密钥是否正确且未过期。
  2. 检查是否 baseUrl 与提供商的预期格式匹配。
  3. 对于持有者令牌，请确保提供完整令牌，而不仅仅是前缀。
Morty Proxy This is a proxified and sanitized view of the page, visit original site.