语言模型 API

语言模型 API 使您能够使用语言模型，并在您的 Visual Studio Code 扩展中集成 AI 驱动的功能和自然语言处理。

您可以在不同类型的扩展中使用语言模型 API。此 API 的典型用途是在聊天扩展中，您可以使用语言模型来解释用户的请求并帮助提供答案。但是，语言模型 API 的使用不限于此场景。您可以在语言或调试器扩展中使用语言模型，或者作为自定义扩展中的命令或任务的一部分。例如，Rust 扩展可以使用语言模型来提供默认名称，以改善其重命名体验。

使用语言模型 API 的过程包括以下步骤

构建语言模型提示
发送语言模型请求
解释响应

以下部分提供有关如何在您的扩展中实现这些步骤的更多详细信息。

链接

构建语言模型提示

为了与语言模型交互，扩展应首先构建其提示，然后向语言模型发送请求。您可以使用提示向语言模型提供有关您正在使用的模型的广泛任务的说明。提示还可以定义解释用户消息的上下文。

在构建语言模型提示时，语言模型 API 支持两种类型的消息

用户 - 用于提供说明和用户的请求
助手 - 用于添加先前语言模型响应的历史记录作为提示的上下文

注意：目前，语言模型 API 不支持使用系统消息。

您可以使用两种方法来构建语言模型提示

LanguageModelChatMessage - 通过提供一个或多个消息作为字符串来创建提示。如果您刚开始使用语言模型 API，则可以使用此方法。
@vscode/prompt-tsx - 通过使用 TSX 语法声明提示。

如果您希望更好地控制语言模型提示的组成方式，可以使用 prompt-tsx 库。例如，该库可以帮助动态调整提示的长度以适应每个语言模型的上下文窗口大小。了解有关 @vscode/prompt-tsx 的更多信息，或浏览聊天扩展示例以开始使用。

要了解有关提示工程概念的更多信息，我们建议阅读 OpenAI 出色的提示工程指南。

提示： 利用丰富的 VS Code 扩展 API 来获取最相关的上下文，并将其包含在您的提示中。例如，包括编辑器中活动文件的内容。

使用 `LanguageModelChatMessage` 类

语言模型 API 提供了 LanguageModelChatMessage 类来表示和创建聊天消息。您可以使用 LanguageModelChatMessage.User 或 LanguageModelChatMessage.Assistant 方法分别创建用户或助手消息。

在以下示例中，第一条消息为提示提供上下文

模型在其回复中使用的角色（在本例中为猫）
模型在生成响应时应遵循的规则（在本例中，通过使用猫的比喻以有趣的方式解释计算机科学概念）

然后，第二条消息提供来自用户的具体请求或指令。它确定要完成的具体任务，给定第一条消息提供的上下文。

const craftedPrompt = [
  vscode.LanguageModelChatMessage.User(
    'You are a cat! Think carefully and step by step like a cat would. Your job is to explain computer science concepts in the funny manner of a cat, using cat metaphors. Always start your response by stating what concept you are explaining. Always include code samples.'
  ),
  vscode.LanguageModelChatMessage.User('I want to understand recursion')
];

发送语言模型请求

在为语言模型构建提示后，您首先使用 selectChatModels 方法选择您要使用的语言模型。此方法返回与指定条件匹配的语言模型数组。如果您正在实现聊天参与者，我们建议您改为使用在聊天请求处理程序中作为 request 对象一部分传递的模型。这确保您的扩展尊重用户在聊天模型下拉列表中选择的模型。然后，您使用 sendRequest 方法向语言模型发送请求。

要选择语言模型，您可以指定以下属性：vendor、id、family 或 version。使用这些属性可以广泛匹配给定供应商或系列的所有模型，或者按其 ID 选择一个特定模型。在 API 参考中了解有关这些属性的更多信息。

注意：目前，语言模型系列支持 gpt-4o、gpt-4o-mini、o1、o1-mini、claude-3.5-sonnet。如果您不确定要使用哪个模型，我们推荐使用 gpt-4o，因为它具有高性能和高质量。对于直接在编辑器中进行的交互，我们推荐使用 gpt-4o-mini，因为它具有高性能。

如果没有模型与指定条件匹配，则 selectChatModels 方法返回一个空数组。您的扩展必须适当地处理这种情况。

以下示例显示了如何选择所有 Copilot 模型，而不管系列或版本如何

const models = await vscode.lm.selectChatModels({
  vendor: 'copilot'
});

// No models available
if (models.length === 0) {
  // TODO: handle the case when no models are available
}

重要提示：Copilot 的语言模型需要用户的同意，扩展才能使用它们。同意以身份验证对话框的形式实现。因此，应作为用户发起的操作（例如命令）的一部分调用 selectChatModels。

选择模型后，您可以通过调用模型实例上的 sendRequest 方法向语言模型发送请求。您传递先前构建的提示，以及任何其他选项和取消令牌。

当您向语言模型 API 发出请求时，请求可能会失败。例如，因为模型不存在，或者用户未同意使用语言模型 API，或者因为超出配额限制。使用 LanguageModelError 来区分不同类型的错误。

以下代码片段显示了如何发出语言模型请求

try {
  const [model] = await vscode.lm.selectChatModels({ vendor: 'copilot', family: 'gpt-4o' });
  const request = model.sendRequest(craftedPrompt, {}, token);
} catch (err) {
  // Making the chat request might fail because
  // - model does not exist
  // - user consent not given
  // - quota limits were exceeded
  if (err instanceof vscode.LanguageModelError) {
    console.log(err.message, err.code, err.cause);
    if (err.cause instanceof Error && err.cause.message.includes('off_topic')) {
      stream.markdown(
        vscode.l10n.t("I'm sorry, I can only explain computer science concepts.")
      );
    }
  } else {
    // add other error handling logic
    throw err;
  }
}

解释响应

发送请求后，您必须处理来自语言模型 API 的响应。根据您的使用场景，您可以将响应直接传递给用户，或者您可以解释响应并执行额外的逻辑。

来自语言模型 API 的响应 (LanguageModelChatResponse) 是基于流的，这使您可以提供流畅的用户体验。例如，当您将 API 与 Chat API 结合使用时，可以通过持续报告结果和进度来实现。

处理流式响应时可能会发生错误，例如网络连接问题。请确保在您的代码中添加适当的错误处理来处理这些错误。

以下代码片段显示了扩展如何注册命令，该命令使用语言模型将活动编辑器中的所有变量名称更改为有趣的猫名称。请注意，扩展将代码流式传输回编辑器，以获得流畅的用户体验。

vscode.commands.registerTextEditorCommand(
  'cat.namesInEditor',
  async (textEditor: vscode.TextEditor) => {
    // Replace all variables in active editor with cat names and words

    const [model] = await vscode.lm.selectChatModels({
      vendor: 'copilot',
      family: 'gpt-4o'
    });
    let chatResponse: vscode.LanguageModelChatResponse | undefined;

    const text = textEditor.document.getText();

    const messages = [
      vscode.LanguageModelChatMessage
        .User(`You are a cat! Think carefully and step by step like a cat would.
        Your job is to replace all variable names in the following code with funny cat variable names. Be creative. IMPORTANT respond just with code. Do not use markdown!`),
      vscode.LanguageModelChatMessage.User(text)
    ];

    try {
      chatResponse = await model.sendRequest(
        messages,
        {},
        new vscode.CancellationTokenSource().token
      );
    } catch (err) {
      if (err instanceof vscode.LanguageModelError) {
        console.log(err.message, err.code, err.cause);
      } else {
        throw err;
      }
      return;
    }

    // Clear the editor content before inserting new content
    await textEditor.edit(edit => {
      const start = new vscode.Position(0, 0);
      const end = new vscode.Position(
        textEditor.document.lineCount - 1,
        textEditor.document.lineAt(textEditor.document.lineCount - 1).text.length
      );
      edit.delete(new vscode.Range(start, end));
    });

    try {
      // Stream the code into the editor as it is coming in from the Language Model
      for await (const fragment of chatResponse.text) {
        await textEditor.edit(edit => {
          const lastLine = textEditor.document.lineAt(textEditor.document.lineCount - 1);
          const position = new vscode.Position(lastLine.lineNumber, lastLine.text.length);
          edit.insert(position, fragment);
        });
      }
    } catch (err) {
      // async response stream may fail, e.g network interruption or server side error
      await textEditor.edit(edit => {
        const lastLine = textEditor.document.lineAt(textEditor.document.lineCount - 1);
        const position = new vscode.Position(lastLine.lineNumber, lastLine.text.length);
        edit.insert(position, (<Error>err).message);
      });
    }
  }
);

注意事项

模型可用性

我们不期望特定模型永远保持受支持状态。当您在扩展中引用语言模型时，请确保在向该语言模型发送请求时采取“防御性”方法。这意味着您应该优雅地处理无法访问特定模型的情况。

选择合适的模型

扩展作者可以选择最适合其扩展的模型。我们建议使用 gpt-4o，因为它具有高性能和高质量。要获取可用模型的完整列表，您可以使用以下代码片段

const allModels = await vscode.lm.selectChatModels(MODEL_SELECTOR);

注意：推荐的 GPT-4o 模型具有 64K tokens 的限制。从 selectChatModels 调用返回的模型对象具有 maxInputTokens 属性，该属性显示令牌限制。随着我们更多地了解扩展如何使用语言模型，这些限制将会扩大。

速率限制

扩展应负责任地使用语言模型，并注意速率限制。VS Code 对用户透明地显示扩展如何使用语言模型，以及每个扩展发送了多少请求以及这如何影响其各自的配额。

由于速率限制，扩展不应将语言模型 API 用于集成测试。在内部，VS Code 使用专用的非生产语言模型进行模拟测试，我们目前正在考虑如何为扩展提供可扩展的语言模型测试解决方案。

测试您的扩展

语言模型 API 提供的响应是非确定性的，这意味着您可能会为相同的请求获得不同的响应。此行为对于测试您的扩展可能具有挑战性。

扩展中用于构建提示和解释语言模型响应的部分是确定性的，因此可以在不使用实际语言模型的情况下进行单元测试。但是，与语言模型本身交互并从中获取响应是非确定性的，并且不容易测试。考虑以模块化的方式设计您的扩展代码，以使您能够单元测试可以测试的特定部分。

发布您的扩展

创建 AI 扩展后，您可以将您的扩展发布到 Visual Studio Marketplace

在发布到 VS Marketplace 之前，我们建议您阅读 Microsoft AI 工具和实践指南。这些指南为负责任地开发和使用 AI 技术提供了最佳实践。
通过发布到 VS Marketplace，您的扩展将遵守 GitHub Copilot 可扩展性可接受的开发和使用策略。
如果您的扩展已经贡献了语言模型 API 以外的功能，我们建议您不要在扩展清单中引入对 GitHub Copilot 的扩展依赖项。这确保了不使用 GitHub Copilot 的扩展用户可以使用非语言模型功能，而无需安装 GitHub Copilot。在这种情况下，请确保在访问语言模型时进行适当的错误处理。
按照发布扩展中所述上传到 Marketplace。

02/06/2025