連結到自訂知識來源

Copilot Studio 內建了如 SharePoint 和 Dataverse 等知識來源。許多組織也使用自己的搜尋端點，如自訂 API、現有企業搜尋系統或 Azure AI 搜尋，同時對所執行的查詢保持完全控制。

Copilot Studio 使用 OnKnowledgeRequested 觸發器支援此情境。任何使用此觸發條件的主題都可作為自訂知識來源，並對生成性答案提供結果。

本文說明如何利用 OnKnowledgeRequested 觸發器在 Copilot Studio 中建立並整合自訂知識來源。你會學習 Copilot Studio 如何重寫查詢、如何連接自己的搜尋 API、如何格式化生成式答案的結果，以及使用自訂知識時的最佳實務。

OnKnowledgeRequested 觸發程序

在以下兩種情況下使用 OnKnowledgeRequested 觸發器：

當編排器判斷需要知識檢索來回答使用者查詢時，
當交談中明確呼叫了生成式回答節點時。

Important

你只能在程式碼檢視中使用 YAML 來設定這個觸發器。沒有視覺設計師支援。

使用 OnKnowledgeRequested 主題的主題可以使用一般主題中無法取得的系統變數：

System.SearchQuery：一個具備語境感知、經過重寫的使用者查詢版本，並針對語義搜尋進行了優化。
System.KeywordSearchQuery：經過重新編寫並針對關鍵字搜尋引擎進行最佳化的查詢。
System.SearchResults：主題儲存經過格式化的知識片段。

Copilot Studio 透過使用對話歷史來智慧重寫查詢，確保保留多回合上下文。

建立自訂知識來源

要建立自訂知識來源，你需要建立一個主題，使用 OnKnowledgeRequested 觸發器來呼叫你的搜尋 API，並將結果轉換成 Copilot Studio 預期的格式。

步驟一：建立觸發器

在 Copilot Studio 建立一個新主題，切換到程式碼檢視，並定義觸發條件OnKnowledgeRequested。

kind: AdaptiveDialog
beginDialog:
  kind: OnKnowledgeRequested
  id: main
  intent: {}
  actions:
    # Actions go here
inputType: {}
outputType: {}

此結構告訴 Copilot Studio，此主題負責滿足知識請求。

步驟 2：新增 HTTP 請求

新增一個 HTTP 動作來呼叫你的搜尋端點。

Example:

- kind: HttpRequestAction
  id: searchRequest
  url: = "https://search-api.contoso.com/search?q=" & System.KeywordSearchQuery
  response: Topic.searchResults
  responseSchema:
    kind: Record
    properties:
      query: String
      results:
        type:
          kind: Table
          properties:
            snippet: String
            title: String
            url: String

把 System.KeywordSearchQuery URL 串接到你的基礎網址，因為 Copilot Studio 會在發送搜尋請求前，自動重寫使用者查詢並包含對話上下文。此步驟對於維持多輪對話的脈絡非常重要。

Tip

與其使用原始 HTTP 要求，你可以使用任何能從搜尋端點取得結果的方法，包括自訂連接器、內建連接器（如 Azure AI 搜尋），或是代理程序流程。

查詢重寫範例

使用者查詢 1：「我們官方的客戶資料保留期限是多久？」
後續問題：「財務資訊會改變嗎？」
後續問題：「有例外嗎？」

重寫查詢為：「資料保留政策例外、客戶及金融資料保留例外、法規豁免、政策例外處理、合規指引」

請注意重寫的查詢信：

解決「那裡」與資料保留政策的關聯
從先前的交互中提取相關資訊：客戶資料 + 財務資料
新增企業政策語言：例外、豁免、法規、指引

步驟 3：轉換結果

自訂知識來源必須輸出 Copilot Studio 預期的結果格式。此格式使用：

內容：片段或摘錄。
ContentLocation （可選）：網址。
標題（可選）：結果標題。

要定義 HTTP 回應的結構，請在 Copilot Studio 使用者介面中設定回應結構。

選擇 從樣本資料 中選取回應資料類型。
選擇 「從範例 JSON 取得結構」。
將你的範例 JSON 資料貼上，即可自動產生架構。

這個過程會在你的 YAML 檔案中產生回應結構。

responseSchema:
  kind: Record
  properties:
    query: String
    results:
      type:
        kind: Table
        properties:
          snippet: String
          title: String
          url: String

接著，將你的 API 回應轉換成符合此格式。將轉換後的資料指派到 System.SearchResults。

轉換範例

kind: AdaptiveDialog
beginDialog:
  kind: OnKnowledgeRequested
  id: main
  intent: {}
  actions:
    - kind: HttpRequestAction
      id: searchRequest
      url: ="https://search-api.contoso.com/search?q=" & System.KeywordSearchQuery
      response: Topic.searchResults
      responseSchema:
        kind: Record
        properties:
          query: String
          results:
            type:
              kind: Table
              properties:
                snippet: String
                title: String
                url: String
    
    - kind: SetVariable
      id: setSearchResults
      variable: System.SearchResults
      value: |-
        =ForAll(Topic.searchResults.results,
        {
          Content: snippet,
          ContentLocation: url,
          Title: title
        })

inputType: {}
outputType: {}

該 SetVariable 動作同時執行兩種操作：

該ForAll函數會將每個搜尋結果轉換，將 snippet 映射到 Contenturl、 ContentLocation 、和 titleTitle。
轉換後的表格會被分配到 System.SearchResults，這是 Copilot Studio 用來產生答案的變數。

Considerations

在建立自訂知識來源時，請牢記這些關鍵考量。

結果限制

Copilot Studio 使用最多 15 個片段 System.SearchResults 來產生回應。如果您的 API 回傳更多結果，請考慮：

實施相關性評分以優先回報最佳結果。
限制你的 API 回應在 15 個結果內。
依相關性排序，然後再轉換。

多個自訂知識主題

你可以透過使用 OnKnowledgeRequested，建立多個主題，每個主題都可以查詢不同的後端系統。 Copilot Studio 在需要知識時會同時調用所有這些功能。這種方法讓你能查詢不同的搜尋端點或實施備援策略。

Warning

結果上限適用於所有合併的知識主題。若主題A回傳10個結果，主題B回傳8個，則僅使用前15個合併結果。

Recommendations

在歸還前先排序或評分結果。
保持回應模式一致。
使用明確的主題名稱和描述。當大型結果集需要相關性過濾時，這種做法非常有用。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-10-08