BYOK(Bring Your Own Key)

코필로트 SDK를 다른 모델 공급자가 제공한 자체 API 키와 함께 사용하여 GitHub Copilot 인증을 우회합니다.

누가 이 기능을 사용할 수 있나요?

GitHub Copilot SDK 는 모든 Copilot 계획에서 사용할 수 있습니다.

이 기사에서

참고

          코필로트 SDK가 현재 공개 미리 보기에 있습니다. 기능 및 가용성은 변경될 수 있습니다.

BYOK(Bring Your Own Key)를 사용하면 코필로트 SDK를 다른 모델 공급자가 제공한 자체 API 키와 함께 사용하여 GitHub Copilot 인증을 우회할 수 있습니다. 엔터프라이즈 배포, 사용자 지정 모델 호스팅 또는 모델 공급자에게 직접 청구하려는 경우에 유용합니다.

지원되는 공급자

공급자형식 값Notes
OpenAI"openai"OpenAI API 및 OpenAI 호환 엔드포인트
Azure OpenAI / Azure AI Foundry
          `"azure"` 또는 `"openai"` | Azure 호스팅 모델( [Azure 엔드포인트 유형](#azure-endpoint-type-confusion) 참조) |

| 인위적 | "anthropic" | 클로드 모델 | | 올라마 섬 | "openai" | OpenAI 호환 API를 통한 로컬 모델 | | Microsoft Foundry 로컬 | "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의 예제는 리포지토리의 BYOK 를 github/copilot-sdk 참조하세요.

공급자 구성 참조

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"입니다. |

Wire 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.

  • URL에 /openai/v1를 포함하지 마세요. SDK가 경로 생성을 처리합니다.

            **Anthropic (`type: "anthropic"`)**

  • Anthropic API를 직접 액세스하는 경우

  • Claude 관련 API 형식을 사용합니다.

구성 예

OpenAI 직통

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",
    },
}

          `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
}

Ollama (로컬)

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

Microsoft Foundry 로컬

          [Microsoft Foundry Local](https://foundrylocal.ai) 을 사용하면 OpenAI 호환 API를 사용하여 AI 모델을 로컬로 실행할 수 있습니다. Foundry 로컬 CLI를 통해 설치한 다음 로컬 엔드포인트에서 SDK를 가리킵니다.
TypeScript
provider: {
    type: "openai",
    baseUrl: "http://localhost:YOUR-PORT/v1",
    // No apiKey needed for local Foundry Local
}

참고

Foundry 로컬은 고정되지 않은 동적 포트에서 시작됩니다. 실행 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 },
            },
        },
    ],
});

첫 번째 호출 후에 결과가 캐시됩니다. 처리기는 CLI의 models.list RPC를 완전히 대체합니다. 서버로의 대체는 발생하지 않습니다.

Python, Go 및 .NET의 예제는 리포지토리의 BYOK 를 github/copilot-sdk 참조하세요.

제한점

ID 제한 사항

BYOK 인증은 정적 자격 증명만 사용합니다. 다음 ID 공급자는 지원되지 않습니다.

  • Microsoft Entra ID(Azure AD) - Entra 관리 ID 또는 서비스 주체를 지원하지 않습니다.
  • 타사 ID 공급자(OIDC, SAML 또는 기타 페더레이션 ID 없음)
  • 관리 ID - Azure 관리 ID는 지원되지 않습니다.

직접 관리하는 API 키 또는 정적 전달자 토큰을 사용해야 합니다.

참고

Entra ID는 전달자 토큰을 발급하지만 이러한 토큰은 수명이 짧고(일반적으로 1시간) Azure ID SDK를 통해 자동 새로 고침이 필요합니다. 이 bearerToken 옵션은 정적 문자열만 허용합니다. SDK가 새 토큰을 요청하는 콜백 메커니즘은 없습니다. Entra 인증이 필요한 장기 실행 워크로드의 경우 고유한 토큰 새로 고침 논리를 구현하고 업데이트된 토큰으로 새 세션을 만들어야 합니다.

기능 제한 사항

일부 Copilot 기능은 BYOK에서 다르게 동작할 수 있습니다.

  • 모델 가용성: 공급자가 지원하는 모델만 사용할 수 있습니다.
  • 속도 제한: 귀하의 공급자의 속도 제한에 따라 달라지며, Copilot와 관련이 없습니다.
  • 사용량 추적: 사용량은 GitHub가 아닌 공급자가 추적합니다.
  • 프리미엄 요청: 프리미엄 요청 할당량에 Copilot 계산되지 않습니다.

공급자별 제한 사항

공급자제한점
Azure AI Foundry (에이아이 파운드리)Entra ID 인증이 없습니다, API 키를 사용해야 합니다.
올라마 섬API 키가 없습니다. 로컬 전용; 모델 지원은 다양합니다.
Microsoft Foundry 로컬로컬 전용; 모델 가용성은 디바이스 하드웨어에 따라 달라집니다. API 키가 필요하지 않습니다.
OpenAIOpenAI 속도 제한 및 할당량이 적용됩니다.

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 엔드포인트 유형 혼동

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. 전달자 토큰의 경우 접두사뿐만 아니라 전체 토큰이 제공되는지 확인합니다.