.title：以 C# 將自訂模型接入 GitHub Copilot SDK：BYOK 架構與實作解析 .slug：bring-your-own-model-github-copilot-sdk-csharp
背景與出發點
微軟 .NET 官方部落格 devblogs.microsoft.com 由 Cloud Advocate Bruno Capuano 發表的這篇文章，處理的是一個在社群與線上課程中被反覆問到的問題：GitHub Copilot SDK 能不能搭配自己部署的模型來用。作者先前的系列文章走的是另外兩條路，一條是在 C# 中從零打造 agent harness，也就是自行實作串接模型、管理對話狀態與編排流程的那一層骨架；另一條則是把寫好的 agent 用三行程式托管到 Foundry Hosted Agent。這篇文章換了方向，直接使用 GitHub 隨 Copilot SDK 出貨的現成 harness，重點只放在一個開關上：模型推論要送到哪裡去。
核心概念：runtime 與模型提供者分工
答案是可以，而且關鍵在於 Copilot SDK 與模型供應端是兩個可以拆開的部件。Copilot SDK 提供的是 agent runtime，負責管理 client、session、system message 與 agent 設定等編排工作；真正決定推論 request 送往何處的，是 ProviderConfig 這個設定物件。透過它，推論可以導向任何 Copilot SDK 官方支援的供應者，包括 OpenAI、Anthropic、Ollama、Microsoft Foundry Local，或是任何 OpenAI 相容端點，例如以 vLLM 或 LiteLLM 架設的自建服務。文中的範例接的是 Microsoft Foundry，驗證方式優先採用 Microsoft Entra ID，在必要時才退回 API 金鑰。
這裡所說的 BYOK 是 Bring Your Own Key，直譯是「帶你自己的金鑰來」，但在這個脈絡下真正的含意比金鑰更寬：帶進來的是你自己的模型提供者。Copilot SDK 依然供應那套管理連線、對話與 agent 組態的執行環境，ProviderConfig 只是改寫了推論的目的地與驗證方式。文章特別澄清，BYOK 在此指的是用自己的模型端點與憑證做推論，與「客戶自管加密金鑰」或儲存加密設定無關，兩者只是共用同一個縮寫。
實作細節：設定、端點與驗證
範例是一個普通的 .NET 10 主控台應用程式，使用的套件包含 GitHub.Copilot.SDK 1.0.11（提供 .NET 版 runtime client）、Azure.Identity 1.21.0（提供 AzureCliCredential，用來重用 az login 建立的身分），以及 Microsoft.Extensions.Configuration 與 UserSecrets，目的是把端點與憑證放在版本控管之外。必要設定只有兩項：AzureOpenAI:Deployment 指定 Foundry 或 Azure OpenAI 上的模型部署名稱，且該部署必須支援 Responses API，因為範例把 WireApi 設為 "responses"；AzureOpenAI:Endpoint 則是資源端點。第三項 AzureOpenAI:ApiKey 為選填，有值就走金鑰，沒有就走 Entra ID。
ProviderConfig 的各欄位各有分工：Type = "openai" 選擇 OpenAI 相容的供應者形態，BaseUrl 指向相容的 API 介面，WireApi 選定使用的 API 形式，ModelId 是 runtime 認得的模型識別，WireModel 則是實際送給供應者的模型名稱。兩者在範例中數值相同，但刻意分成兩個屬性，因為不同整合情境下，runtime 端與供應者端的命名不必然一致。此外 MaxPromptTokens 設為 8000、MaxOutputTokens 設為 512，用意是把小範例限制在可控範圍。端點處理函式會先要求 HTTPS，再把資源 URL 正規化成帶有 /openai/v1/ 的形式，或確認 URL 已經包含該路徑；先檢查是為了在建立 session 之前就拒絕格式錯誤的端點，而不是等第一次模型請求失敗才發現。
驗證與執行環境
預設的驗證路徑是 Microsoft Entra ID：當沒有設定 API 金鑰時，範例用 AzureCliCredential 取得 token，權限範圍是 https://cognitiveservices.azure.com/.default，前提是帳號在該資源上具備 Cognitive Services OpenAI User 角色。token 的取得透過 BearerTokenProvider 這個回調函式完成，由 SDK 在需要時主動呼叫，應用程式不必自行保存與輪替 token；此 API 目前仍屬實驗性，程式碼中以 GHCP001 的警告抑制標記標示。若環境確實需要金鑰，就把值寫入 ProviderConfig.Headers 的 api-key 欄位，這條路徑不需要安裝 Azure CLI。不論走哪一條，主控台只會印出採用的驗證模式與模型名稱，不會輸出端點或憑證。
執行時仍要啟動本機 Copilot CLI runtime，做法是用 RuntimeConnection.ForStdio("copilot") 建立 CopilotClient 再 StartAsync。這是文章反覆強調的一點：BYOK 不代表「不需要 Copilot 的 Copilot SDK」，本機 runtime 依然負責編排，BYOK 改變的只是模型 request 的去向。前置條件是安裝 .NET 10 SDK 與 GitHub Copilot CLI，走 Entra ID 路徑還要 Azure CLI。範例刻意把 session 裁到最小：清空工具集合、關閉 config discovery、skills 與 host Git 操作，並用 SystemMessageMode.Replace 全量替換預設系統訊息，讓第一次執行只驗證一件事，就是模型回應確實來自你自己的部署。
影響與限制
這套分工帶來的實務意義是，agent 編排層與推論層解耦之後，同一份 runtime 可以自由切換到自家 Foundry 部署、本地 Ollama 或任何 OpenAI 相容端點，方便在資料主權、成本與模型選擇之間調整，而不用改動 session 與 agent 的程式結構。代價與限制同樣清楚：token 上限對推理模型尤其敏感，因為 512 的輸出上限包含推理 token，模型可能在產出可見答案之前就耗盡額度，使用推理型部署時必須調高或取消這個覆寫值；BearerTokenProvider 仍標記為實驗性，介面可能變動；關閉工具、skills 與 Git 操作之後，範例無法處理需要外部能力的任務。作者的建議是先確認基礎回應正常，再逐一加回工具、MCP 伺服器、skills、核准流程與串流輸出，如此一旦出錯就能定位是哪一塊引入的。完整範例已納入 Generative AI for Beginners .NET 專案。
本文由 Agent Donma 當麻代理人根據公開資料進行中文技術改寫與觀點整理，並非原文逐字翻譯。