Thanks to visit codestin.com
Credit goes to docs.github.com

приносите свой ключ (BYOK)

Используйте Второй пилот SDK свои API-ключи от разных поставщиков моделей, обходя GitHub Copilot аутентификацию.

Кто может использовать эту функцию?

GitHub Copilot SDK Доступна со всеми Copilot тарифными планами.

В этой статье

Примечание.

          Второй пилот SDK в настоящее время находится в public preview. Функциональность и доступность могут меняться.

Bring your own key (BYOK) позволяет использовать Второй пилот SDK его с собственными API-ключами от поставщиков моделей, обходя GitHub Copilot аутентификацию. Это полезно для корпоративных развертываний, хостинга кастомных моделей или когда вам нужен прямой биллинг с вашим поставщиком модели.

Поддерживаемые поставщики

ПоставщикЗначение типаПримечания
OpenAI"openai"API OpenAI и совместимые с OpenAI конечные точки
Azure OpenAI / Azure AI Foundry
          `"azure"` или `"openai"` | Azure-hosted models (см. [Azure endpoint types](#azure-endpoint-type-confusion)) |

| Антропик | "anthropic" | Модели Claude | | Ollama | "openai" | Локальные модели через совместимый с OpenAI API | | Microsoft Foundry Local | "openai" | Запускайте модели ИИ локально на вашем устройстве через совместимый с OpenAI API | | Другие совместимые с 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();

Замените YOUR-RESOURCE имя ресурса Azure и YOUR-DEPLOYMENT-NAME имя развертывания модели. Установите FOUNDRY_API_KEY переменную среды на ваш Azure API key.

Для примеров в Python, Go и .NET см. BYOK в github/copilot-sdk репозитории. Для Java см. репозиторийgithub/copilot-sdk-java.

Ссылка конфигурации провайдера

Поля ProviderConfig

ПолеТипОписание
type
          `"openai"`
          \|
          `"azure"`
          \|
          `"anthropic"`
         | Тип провайдера. По умолчанию — `"openai"`. |

| baseUrl | струна | Обязательно. URL API endpoint. | | apiKey | струна | Ключ API. Опционально для местных провайдеров, таких как Ollama. | | bearerToken | струна | Аутентификация токена предъявлятеля. Имеет приоритет над apiKey. | | wireApi | "completions" | "responses" | Формат API. По умолчанию — "completions". | | azure.apiVersion | струна | Azure API version. По умолчанию — "2024-10-21". |

Формат API провода

Настройка wireApi определяет, какой формат API OpenAI использовать:

          `"completions"`
          ** (по умолчанию): API завершения чата (`/chat/completions`). Используйте для большинства моделей.

          `"responses"`
          **: API Responses. Используйте для моделей серии GPT-5, поддерживающих новый формат ответов.

Заметки, специфичные для типа

          **OpenAI (`type: "openai"`)**

  • Работает с API OpenAI и любыми совместимыми с OpenAI конечными точками.

  • baseUrl должно включать полный путь, например, https://api.openai.com/v1.

            **Azure (`type: "azure"`)**

  • Используйте для нативных Azure OpenAI конечных точек.

  • baseUrl Например, должен быть только хост https://YOUR-RESOURCE.openai.azure.com.

  • Не указывайте /openai/v1 в URL — SDK занимается построением пути.

            **Антропический (`type: "anthropic"`)**

  • Для прямого доступа к Anthropic API.

  • Использует специфический формат API для Claude.

Примеры конфигураций

OpenAI Direct

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

Azure OpenAI (native Azure endpoint)

Использование 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",
    },
}

Замените YOUR-RESOURCE имя вашего ресурса Azure.

Azure AI Foundry (OpenAI-совместимая конечная точка)

Для развертывания Azure AI Foundry с /openai/v1/ конечными точками используйте 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) позволяет запускать модели ИИ локально с помощью API, совместимого с OpenAI. Установите его через 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.

Антропик

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 },
            },
        },
    ],
});

Результаты кэшируются после первого вызова. Обработчик полностью заменяет RPC CLI models.list — резервного перехода к серверу не происходит.

Для примеров в Python, Go и .NET см. BYOK в github/copilot-sdk репозитории. Для Java см. репозиторийgithub/copilot-sdk-java.

Ограничения

Ограничения идентичности

Аутентификация BYOK использует только статические учетные данные. Следующие поставщики идентификации не поддерживаются:

  • Microsoft Entra ID (Azure AD) — нет поддержки управляемых идентичностей Entra or service principals.
  • Сторонние поставщики идентификации — никаких OIDC, SAML или других федеративных идентификаторов.
  • Управляемые идентичности — Azure Managed Identity не поддерживается.

Вы должны использовать API или статический токен носителя, которым управляете сами.

Примечание.

Хотя Entra ID действительно выпускает носительские токены, эти токены недолговечны (обычно один час) и требуют автоматического обновления через Azure Identity SDK. Опция принимает только статическую строку — нет механизма bearerToken обратного вызова, чтобы SDK запросил свежие токены. Для длительных нагрузок, требующих аутентификации Entra, потребуется реализовать собственную логику обновления токена и создавать новые сессии с обновлёнными токенами.

Ограничения функций

Некоторые Copilot функции могут вести себя иначе с BYOK:

  • Доступность моделей: доступны только модели, поддерживаемые вашим провайдером.
  • Ограничение тарифов: В зависимости от тарифных лимитов вашего провайдера, а Copilotне ''s.
  • Отслеживание использования: Использование отслеживается вашим провайдером, а не GitHub.
  • Запросы на премии: не учитываются в Copilot квотах на премии.

Ограничения, специфичные для поставщика,

ПоставщикОграничения
Azure AI FoundryНет аутентификации Entra ID; должны использовать API-ключи.
OllamaНет ключа API; только местные; Поддержка моделей варьируется.
Microsoft Foundry LocalТолько местные; Доступность модели зависит от аппаратного обеспечения устройства; API-ключ не требуется.
OpenAIПодчиняется ограничениям и квотам OpenAI.

Troubleshooting

Ошибка «Модель не указана»

При использовании 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 endpoint type confusion

Для конечных точек 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 работает и доступна:

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. Для жетонов предъявителя убедитесь, что весь токен префикс, а не просто префикс.