🚀 在 VS Code 中！

LanguageModelTool API

在本擴充功能指南中，您將學習如何建立語言模型工具，以及如何在聊天擴充功能中實作工具呼叫。

什麼是 LLM 中的工具呼叫？

工具呼叫讓您能夠擴展大型語言模型 (LLM) 的功能，方法是將其連接到外部工具和系統，以執行超出文字處理範圍的工作。

語言模型工具是一個函數，可以作為語言模型請求的一部分來調用。例如，您可能有一個函數可以從資料庫檢索資訊、尋找檔案或執行一些計算。您可以在您的擴充功能中實作語言模型工具，或使用來自其他擴充功能的公開可用工具。

LLM 永遠不會實際執行工具本身，而是 LLM 會產生可用於呼叫您的工具的參數，然後您的程式碼可以選擇如何處理，方法是呼叫指示的函數。您的擴充功能始終完全控制工具呼叫流程。

請參閱 OpenAI 文件中關於函數呼叫的更多資訊。

為什麼要使用工具呼叫？

在聊天擴充功能中，您可能想要使用工具呼叫有多種情境。一些範例包括

  • 讓 LLM 動態要求更多內容。例如，您可以使用工具從資料庫檢索資訊，或尋找相關檔案。
  • 讓 LLM 動態採取某些動作。LLM 本身無法執行計算或呼叫其他系統。例如，使用工具執行終端機命令並將輸出傳回給 LLM。
  • 連結由另一個 VS Code 擴充功能貢獻的某些內容/行為。例如，您可能有一個工具使用 Git 擴充功能來檢索關於目前儲存庫的資訊。

工具呼叫流程

聊天擴充功能中的工具呼叫流程如下

  1. 檢索相關工具的清單

  2. 將請求傳送至 LLM，提供要考慮的工具定義清單

  3. LLM 產生回應，其中可能包括一個或多個調用工具的請求

  4. 使用 LLM 回應中提供的參數值來調用工具

  5. 將另一個請求傳送至 LLM，包含工具結果

  6. LLM 產生最終使用者回應，其中可能包含工具回應

    如果 LLM 回應包含更多工具調用請求，請重複步驟 4-6，直到沒有更多工具請求為止。

使用聊天擴充功能程式庫實作工具呼叫

您可以使用 @vscode/chat-extension-utils 程式庫來簡化聊天擴充功能中呼叫工具的流程。

在您的聊天參與者的 vscode.ChatRequestHandler 函數中實作工具呼叫。

  1. 判斷目前聊天內容的相關工具。您可以使用 vscode.lm.tools 存取所有可用的工具。

    以下程式碼片段示範如何篩選工具，僅保留具有特定標籤的工具。

    const tools =
  request.command === 'all'
    ? vscode.lm.tools
    : vscode.lm.tools.filter(tool => tool.tags.includes('chat-tools-sample'));

  2. 使用 sendChatParticipantRequest 將請求和工具定義傳送至 LLM。

    const libResult = chatUtils.sendChatParticipantRequest(
  request,
  chatContext,
  {
    prompt: 'You are a cat! Answer as a cat.',
    responseStreamOptions: {
      stream,
      references: true,
      responseText: true
    },
    tools
  },
  token
);

    ChatHandlerOptions 物件具有以下屬性

    • prompt：（選用）聊天參與者提示的指示。
    • model：（選用）用於請求的模型。如果未指定，則使用聊天內容中的模型。
    • tools：（選用）要考慮用於請求的工具清單。
    • requestJustification：（選用）描述提出請求原因的字串。
    • responseStreamOptions：（選用）啟用 sendChatParticipantRequest 將回應串流回 VS Code。您可以選擇性地啟用參考和/或回應文字。

  3. 從 LLM 傳回結果。這可能包含錯誤詳細資訊或工具呼叫中繼資料。

    return await libResult.result;

此工具呼叫範例的完整原始碼可在 VS Code 擴充功能範例儲存庫中找到。

自行實作工具呼叫

對於更進階的情境，您也可以自行實作工具呼叫。您可以選擇性地使用 @vscode/prompt-tsx 程式庫來製作 LLM 提示。透過自行實作工具呼叫，您可以更精細地控制工具呼叫流程。例如，執行額外的驗證，或在將工具回應傳送至 LLM 之前以特定方式處理它們。

請檢視在 VS Code 擴充功能範例儲存庫中使用 prompt-tsx 實作工具呼叫的完整原始碼。

建立語言模型工具

在呼叫工具時，您可以呼叫其他擴充功能貢獻的公開可用語言模型工具，或者您可以建立自己的工具。當您建立工具時，您可以選擇是否向 VS Code API 註冊它，或者僅在您的擴充功能中將其用作私人工具。

當您使用 VS Code API 發佈工具時，該工具對所有擴充功能都可用。

決定註冊工具還是將其用作私人工具

在以下情況下，向 VS Code API 註冊工具

  • 該工具對其他擴充功能有意義，並且可以在不針對特定工具進行特殊處理的情況下使用
  • 擴充功能需要提供進度訊息和確認

在以下情況下，使用私人工具

  • 該工具無法公開，例如因為它特定於您的公司或檢索非公開資料
  • 該工具需要一些特殊處理，並且特定於您的擴充功能

實作語言模型工具

若要實作語言模型工具

  1. 在 package.json 中的 contributes 屬性中定義工具

    以下範例示範如何定義一個工具來計算標籤群組中活動標籤的數量。

    "contributes": {
    "languageModelTools": [
        {
            "name": "chat-tools-sample_tabCount",
            "tags": [
                "editors",
                "chat-tools-sample"
            ],
            "toolReferenceName": "tabCount",
            "displayName": "Tab Count",
            "modelDescription": "The number of active tabs in a tab group",
            "icon": "$(files)",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "tabGroup": {
                        "type": "number",
                        "description": "The index of the tab group to check. This is optional- if not specified, the active tab group will be checked.",
                        "default": 0
                    }
                }
            }
        }
    ]
}

    語言模型工具具有以下屬性

    • name：工具的唯一名稱。這用於在擴充功能實作程式碼中參考工具。
    • tags：描述工具的標籤陣列。這用於篩選與特定請求相關的工具清單。
    • toolReferenceName：如果啟用，使用者可以在聊天提示中透過 # 參考工具的名稱。
    • displayName：工具的使用者友善名稱，用於在 UI 中顯示。
    • modelDescription：工具的描述，語言模型可以使用它來選取工具。
    • icon：要在 UI 中顯示的工具圖示。
    • inputSchema：JSON Schema，描述工具的輸入參數。這由語言模型用於為工具調用提供參數值。

  2. （選用）使用 vscode.lm.registerTool 註冊工具

    如果您想要發佈工具以供其他擴充功能使用，則必須使用 vscode.lm.registerTool API 註冊工具。提供您在 package.json 檔案中指定的工具名稱。

    export function registerChatTools(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.lm.registerTool('chat-tools-sample_tabCount', new TabCountTool())
  );
}

  3. 透過實作 vscode.LanguageModelTool<> 介面來實作語言模型工具。

    • 實作 prepareInvocation 以為工具調用提供確認訊息。

      以下範例示範如何為標籤計數工具提供確認訊息。

      async prepareInvocation(
    options: vscode.LanguageModelToolInvocationPrepareOptions<ITabCountParameters>,
    _token: vscode.CancellationToken
) {
    const confirmationMessages = {
        title: 'Count the number of open tabs',
        message: new vscode.MarkdownString(
            `Count the number of open tabs?` +
            (options.input.tabGroup !== undefined
                ? ` in tab group ${options.input.tabGroup}`
                : '')
        ),
    };

    return {
        invocationMessage: 'Counting the number of tabs',
        confirmationMessages,
    };
}

    • 定義一個介面，描述工具輸入參數。此介面在 invoke 方法中使用。

      以下範例顯示標籤計數工具的介面。

      export interface ITabCountParameters {
  tabGroup?: number;
}

    • 實作 invoke，在調用工具時呼叫。它在 options 參數中接收工具輸入參數。

      以下範例顯示標籤計數工具的實作。工具的結果是 vscode.LanguageModelToolResult 類型的實例。

      async invoke(
    options: vscode.LanguageModelToolInvocationOptions<ITabCountParameters>,
    _token: vscode.CancellationToken
) {
    const params = options.input;
    if (typeof params.tabGroup === 'number') {
        const group = vscode.window.tabGroups.all[Math.max(params.tabGroup - 1, 0)];
        const nth =
            params.tabGroup === 1
                ? '1st'
                : params.tabGroup === 2
                    ? '2nd'
                    : params.tabGroup === 3
                        ? '3rd'
                        : `${params.tabGroup}th`;
        return new vscode.LanguageModelToolResult([new vscode.LanguageModelTextPart(`There are ${group.tabs.length} tabs open in the ${nth} tab group.`)]);
    } else {
        const group = vscode.window.tabGroups.activeTabGroup;
        return new vscode.LanguageModelToolResult([new vscode.LanguageModelTextPart(`There are ${group.tabs.length} tabs open.`)]);
    }
}

請檢視在 VS Code 擴充功能範例儲存庫中實作語言模型工具的完整原始碼。

開始使用

相關內容

02/06/2025