使用 AI 應用程式範本延伸模組建立 .NET AI 應用程式來與自訂數據聊天

在本快速入門中，您將瞭解如何使用 .NET AI 應用程式範本建立 .NET AI 應用程式來與自定義數據聊天。 此範本的設計目的是藉由為您處理常見的設定工作和設定，簡化使用 .NET 建置 AI 應用程式的入門體驗。

先決條件

安裝 .NET AI 應用程式範本

AI Chat Web App 範本可透過 NuGet 作為範本套件。 使用 dotnet new install 命令來安裝套件：

dotnet new install Microsoft.Extensions.AI.Templates

建立 .NET AI 應用程式

安裝 AI 應用程式範本之後，您可以使用它們透過 Visual Studio UI、Visual Studio Code 或 .NET CLI 來建立入門應用程式。

  1. 在 Visual Studio 內，導航至 [檔案] [> 新增] [> 專案]。
  2. 在 [建立新專案 畫面上，搜尋 AI Chat Web App。 選取相符的結果，然後選擇 [下一步] 。
  3. 在 [設定新專案 ] 畫面的 []，輸入專案所需的名稱和位置，然後選擇 [下一步]。
  4. 在 [附加資訊 畫面：
    • 針對 [Framework] 選項，選取 [.NET 9.0]。
    • 針對 [AI 服務提供者] 選項，選取 [GitHub Models]。
    • 針對 [向量存放區] 選項，選取 [本機磁碟上（用於原型設計）]。
  5. 選取 建立 以完成此過程。

探索範例應用程式

您建立的範例應用程式是一個 Blazor Interactive Server Web 應用程式，其預先設定為一般 AI 和數據服務。 應用程式可以幫您解決下列問題：

  • 在 Microsoft.Extensions.AI 檔案中包含基本的 csproj 套件和其他相依性，以協助您開始使用 AI。
  • 建立各種 AI 服務，並在 Program.cs 檔案中註冊它們以進行相依性插入：
    • 與產生式 AI 模型來回聊天的 IChatClient 服務
    • 用來產生內嵌的 IEmbeddingGenerator 服務，這對向量搜尋功能至關重要
    • 作為記憶體內向量存放區的 JsonVectorStore
  • 註冊一個 SQLite 資料庫環境服務來處理導入文件。 應用程式已預先設定為內嵌您新增至專案 Data 資料夾的任何檔，包括提供的範例檔案。
  • 使用 Blazor 元件提供完整的聊天 UI。 UI 會處理 AI 回應的豐富格式，並提供響應數據引文等功能。

設定 GitHub 模型的存取權

若要從程式代碼向 GitHub 模型進行驗證，您必須 建立 GitHub 個人存取令牌：

  1. 流覽至 [開發人員設定] 底下 GitHub 帳戶設定的 [個人存取令牌] 頁面。
  2. 選擇 產生新的權杖。
  3. 輸入令牌的名稱，然後在 [ 許可權] 底下，將 [模型 ] 設定為 [存取：只讀]。
  4. 選取頁面底部的生成令牌。
  5. 複製令牌以供後續步驟使用。

設定應用程式

AI 聊天網路應用程式一經創建就幾乎準備就緒。 不過，您必須將應用程式設定為使用您為 GitHub Models 設定的個人存取令牌。 根據預設，應用程式範本會在專案的本機 .NET 使用者秘密中搜尋此值。 您可以使用 Visual Studio UI 或 .NET CLI 來管理用戶密碼。

注意

如果你的應用程式已經啟用了 Aspire，請跳到 Aspire 設定 區塊。

  1. 以滑鼠右鍵按一下 [方案總管] 中的專案，然後選取 [管理使用者密碼]。 這會開啟 secrets.json 檔案，您可以在其中儲存 API 金鑰，而不用在原始檔控制中追蹤金鑰。

  2. 新增下列鍵和值：

    {
    "GitHubModels:Token": "<your-gh-models-access-token>"
}

Aspire 設定

若要使用 AI 聊天網頁應用程式 範本搭配 Aspire 編排，請新增以下設定：

  1. 以滑鼠右鍵按一下 *.AppHost [方案總管] 中的專案，然後選取 [管理使用者密碼]。 這會開啟 secrets.json 檔案，您可以在其中儲存 API 金鑰，而不用在原始檔控制中追蹤金鑰。

  2. 新增下列鍵和值：

    {
    "ConnectionStrings:openai": "Endpoint=https://models.inference.ai.azure.com;Key=<your-gh-models-access-token>"
}

根據預設，應用程式範本會使用 gpt-4o-mini 和 text-embedding-3-small 模型。 若要嘗試其他模型，請更新 Program.cs中的名稱參數：

var chatClient = ghModelsClient.AsChatClient("gpt-4o-mini");
var embeddingGenerator = ghModelsClient.AsEmbeddingGenerator("text-embedding-3-small");

先決條件

安裝 .NET AI 應用程式範本

AI Chat Web App 範本可透過 NuGet 作為範本套件。 使用 dotnet new install 命令來安裝套件：

dotnet new install Microsoft.Extensions.AI.Templates

建立 .NET AI 應用程式

安裝 AI 應用程式範本之後，您可以使用它們透過 Visual Studio UI、Visual Studio Code 或 .NET CLI 來建立入門應用程式。

  1. 在 Visual Studio 內，導航至 [檔案] [> 新增] [> 專案]。
  2. 在 [建立新專案 畫面上，搜尋 AI Chat Web App。 選取相符的結果，然後選擇 [下一步] 。
  3. 在 [設定新專案 ] 畫面的 []，輸入專案所需的名稱和位置，然後選擇 [下一步]。
  4. 在 [附加資訊 畫面：
    • 針對 [Framework] 選項，選取 [.NET 9.0]。
    • 針對 [AI 服務提供者] 選項，選取 [Azure OpenAI]。
    • 請確定 [使用無金鑰驗證於 Azure 服務] 複選框已被勾選。
    • 針對 [向量存放區] 選項，選取 [本機磁碟上（用於原型設計）]。
  5. 選取 建立 以完成此過程。

探索範例應用程式

您建立的範例應用程式是一個 Blazor Interactive Server Web 應用程式，其預先設定為一般 AI 和數據服務。 應用程式範本會為您處理下列事宜：

  • 在 Microsoft.Extensions.AI 檔案中包含基本的 .csproj 套件和其他相依性，以協助您開始使用 AI。
  • 建立各種 AI 服務，並在 Program.cs 檔案中註冊它們以進行相依性插入：
    • IChatClient 與產生式 AI 模型互動聊天的服務。
    • 用來產生內嵌的IEmbeddingGenerator服務，是向量搜尋功能中不可缺少的關鍵元素。
    • JsonVectorStore，做為記憶體內部向量存放區。
  • 註冊一個 SQLite 資料庫環境服務來處理導入文件。 應用程式已預先設定為內嵌您新增至專案 wwwroot/Data 資料夾的任何檔，包括提供的範例檔案。
  • 使用 Blazor 元件提供完整的聊天 UI。 UI 會處理 AI 回應的豐富格式，並提供響應數據引文等功能。

建立並驗證 Azure OpenAI 服務

若要搭配 Azure OpenAI 使用 .NET AI 範本，您必須建立 Azure OpenAI 服務並進行驗證。

建立 Azure OpenAI 服務

  1. 如果您還沒有可用的 Azure OpenAI 服務資源，請建立一個。

  2. 將 gpt-4o-mini 和 text-embedding-3-small 模型部署到您的 Azure OpenAI 服務資源。 建立這些部署時，請為它們提供與模型 （gpt-4o-mini 和 text-embedding-3-small） 相同的名稱，使其符合預設範本值。 若要瞭解如何部署模型，請參閱 Azure OpenAI 檔中 建立資源。

向 Azure OpenAI 服務進行驗證

AI 樣本會使用 Microsoft Entra ID 進行順暢且無密鑰的驗證。 它會利用 DefaultAzureCredential 在本機執行時，自動偵測及使用您開發工具中的憑證。 若要連線到服務，請確定您的開發人員帳戶已指派適當的角色，並已登入您的本機開發工具。

  1. 將角色指派給開發人員帳戶，以存取 Azure OpenAI 資源：

    • 在 Azure 入口網站中，導覽至 Azure OpenAI 資源的概覽頁面。
    • 從左側導覽選擇 存取控制 （IAM）。
    • 將角色指派新增至您的 Azure 帳戶以用於Azure AI Developer角色。

  2. 使用您指派角色的 Azure 帳戶登入本地開發工具，例如 Visual Studio 或 Azure CLI。

設定應用程式

AI 聊天 Web 應用程式，一經創建幾乎可以立即啟用。 不過，您必須為 Azure OpenAI 服務提供端點，應用程式才能連線。 根據預設，應用程式範本會在專案的本機 .NET 使用者秘密中搜尋此值。 您可以使用 Visual Studio UI 或 .NET CLI 來管理用戶密碼。

注意

若要避免驗證錯誤，請確定您已使用 Azure OpenAI 資源上指派 Azure AI 開發人員 角色的使用者登入 Visual Studio 或 Azure CLI。

  1. 在 Visual Studio 中，以滑鼠右鍵按兩下方案總管中的專案，然後選取 [管理用戶密碼]。 這會開啟 secrets.json 檔案，您可以在其中儲存 API 金鑰，而不用在原始檔控制中追蹤金鑰。

  2. 新增下列鍵和值：

    {
    "AzureOpenAi:Endpoint": "<your-endpoint>"
}

根據預設，應用程式範本會假設您的 AI 模型部署名稱與基礎模型相同。 如有必要，請更新部署名稱參數，以符合您的 gpt-4o-mini 和 text-embedding-3-small 部署名稱：

// Update these parameter values to match your Azure OpenAI model deployment names
var chatClient = azureOpenAi.AsChatClient("gpt-4o-mini");
var embeddingGenerator = azureOpenAi.AsEmbeddingGenerator("text-embedding-3-small");

先決條件

安裝 .NET AI 應用程式範本

AI Chat Web App 範本可透過 NuGet 作為範本套件。 使用 dotnet new install 命令來安裝套件：

dotnet new install Microsoft.Extensions.AI.Templates

建立 .NET AI 應用程式

安裝 AI 應用程式範本之後，您可以使用它們透過 Visual Studio UI、Visual Studio Code 或 .NET CLI 來建立入門應用程式。

  1. 在 Visual Studio 內，導航至 [檔案] [> 新增] [> 專案]。
  2. 在 [建立新專案 畫面上，搜尋 AI Chat Web App。 選取相符的結果，然後選擇 [下一步] 。
  3. 在 [設定新專案 ] 畫面的 []，輸入專案所需的名稱和位置，然後選擇 [下一步]。
  4. 在 [附加資訊 畫面：
    • 針對 [Framework] 選項，選取 [.NET 9.0]。
    • 針對 [AI 服務提供者] 選項，選取 [OpenAI]。
    • 針對 [向量存放區] 選項，選取 [本機磁碟]（用於原型設計）。
  5. 選取 建立 以完成此過程。

探索範例應用程式

您建立的範例應用程式是一個 Blazor Interactive Server Web 應用程式，其預先設定為一般 AI 和數據服務。 應用程式範本會為您處理下列事宜：

  • 在 Microsoft.Extensions.AI 檔案中包含基本的 .csproj 套件和其他相依性，以協助您開始使用 AI。
  • 建立各種 AI 服務，並在 Program.cs 檔案中註冊它們以進行相依性插入：
    • IChatClient 與產生式 AI 模型互動聊天的服務。
    • 用來產生內嵌的IEmbeddingGenerator服務，是向量搜尋功能中不可缺少的關鍵元素。
    • JsonVectorStore，做為記憶體內部向量存放區。
  • 註冊一個 SQLite 資料庫環境服務來處理導入文件。 應用程式已預先設定為內嵌您新增至專案 wwwroot/Data 資料夾的任何檔，包括提供的範例檔案。
  • 使用 Blazor 元件提供完整的聊天 UI。 UI 會處理 AI 回應的豐富格式，並提供響應數據引文等功能。

設定應用程式

AI 聊天 Web 應用程式，一經創建幾乎可以立即啟用。 不過，您必須為 OpenAI 服務提供金鑰，應用程式將用來連線和驗證。 根據預設，應用程式範本會在專案的本機 .NET 使用者秘密中搜尋此值。 您可以使用 Visual Studio UI 或 .NET CLI 來管理用戶密碼。

  1. 在 Visual Studio 中，以滑鼠右鍵按兩下方案總管中的專案，然後選取 [管理用戶密碼]。 這會開啟 secrets.json 檔案，您可以在其中儲存 API 金鑰，而不用在原始檔控制中追蹤金鑰。

  2. 新增下列鍵和值：

    {
    "OpenAi:Key": "<your-OpenAI-key>"
}

根據預設，應用程式範本會假設使用特定 AI 模型。 如有必要，請更新模型名稱參數，以符合您想要設為目標的模型：

// Update these parameter values to match your preferred OpenAI models
var chatClient = openAIClient.AsChatClient("gpt-4o-mini");
var embeddingGenerator = openAIClient.AsEmbeddingGenerator("text-embedding-3-small");

先決條件

安裝 .NET AI 應用程式範本

AI Chat Web App 範本可透過 NuGet 作為範本套件。 使用 dotnet new install 命令來安裝套件：

dotnet new install Microsoft.Extensions.AI.Templates

建立 .NET AI 應用程式

安裝 AI 應用程式範本之後，您可以使用它們透過 Visual Studio UI、Visual Studio Code 或 .NET CLI 來建立入門應用程式。

  1. 在 Visual Studio 內，導航至 [檔案] [> 新增] [> 專案]。
  2. 在 [建立新專案 畫面上，搜尋 AI Chat Web App。 選取相符的結果，然後選擇 [下一步] 。
  3. 在 [設定新專案 ] 畫面的 []，輸入專案所需的名稱和位置，然後選擇 [下一步]。
  4. 在 [附加資訊 畫面：
    • 針對 [Framework] 選項，選取 [.NET 9.0]。
    • 針對 [AI 服務提供者] 選項，選取 [Ollama]。
    • 針對 [向量存放區] 選項，選取 [本機磁碟]（用於原型設計）。
  5. 選取 建立 以完成此過程。

探索範例應用程式

您建立的範例應用程式是一個 Blazor Interactive Server Web 應用程式，其預先設定為一般 AI 和數據服務。 應用程式範本會為您處理下列事宜：

  • 在 Microsoft.Extensions.AI 檔案中包含基本的 .csproj 套件和其他相依性，以協助您開始使用 AI。
  • 建立各種 AI 服務，並在 Program.cs 檔案中註冊它們以進行相依性插入：
    • IChatClient 與產生式 AI 模型互動聊天的服務。
    • 用來產生內嵌的IEmbeddingGenerator服務，是向量搜尋功能中不可缺少的關鍵元素。
    • JsonVectorStore，做為記憶體內部向量存放區。
  • 註冊一個 SQLite 資料庫環境服務來處理導入文件。 應用程式已預先設定為內嵌您新增至專案 wwwroot/Data 資料夾的任何檔，包括提供的範例檔案。
  • 使用 Blazor 元件提供完整的聊天 UI。 UI 會處理 AI 回應的豐富格式，並提供響應數據引文等功能。

設定應用程式

AI 聊天 Web 應用程式，一經創建幾乎可以立即啟用。 不過，您應該在執行應用程式之前，先確認特定組態符合您的需求。

  1. 在本機終端機視窗中，確認 Ollama 是否已在電腦上運行，請使用 ollama serve 命令：

    ollama serve

  2. 根據預設，應用程式範本會以 http://localhost:11434 的預設 Ollama 主機位址為目標，並假設使用 llama3.2 和 all-minilm AI 模型。 使用下列命令將這些模型向下拉到您的裝置上：

    ollama pull llama3.2
ollama pull all-minilm

    如果您想要使用替代模型，請使用相同的 ollama pull 命令來向下提取這些模型。

  3. 確認客戶端設定程式碼參數符合您慣用的模型：

    // Update these parameter values to match your preferred OpenAI models
IChatClient chatClient = new OllamaApiClient(
    new Uri("http://localhost:11434"),
    "llama3.2");
IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator = new OllamaApiClient(
    new Uri("http://localhost:11434"),
    "all-minilm");

執行及測試應用程式

  1. 選取 Visual Studio 頂端的 [執行] 按鈕以啟動應用程式。 稍後，您應該會在瀏覽器中看到以下的 UI 載入：

    顯示 .NET AI 應用程式範本 UI 的螢幕快照。

  2. 在輸入方塊中輸入提示，例如 「生存套件中的一些基本工具是什麼？」 詢問 AI 模型有關範例檔案內嵌數據的問題。

    顯示 .NET AI 應用程式範本交談UI的螢幕快照。

    應用程式會以問題的答案回應，並提供找到數據的引文。 您可以按兩下其中一個引文，以導向至範例檔案的相關區段。

後續步驟

  • Last updated on