语言模型API

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

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

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

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

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

链接

构建语言模型提示

要与语言模型交互，扩展应首先制作其提示，然后向语言模型发送请求。您可以使用提示为语言模型提供关于您使用该模型的广泛任务的指令。提示还可以定义用户消息被解释的上下文。

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

用户 - 用于提供指令和用户的请求
Assistant - 用于将之前语言模型响应的历史记录作为上下文添加到提示中

注意: 目前，语言模型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-preview, o1-mini, claude-3.5-sonnet, gemini-1.5-pro。如果您不确定使用哪个模型，我们推荐使用 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与聊天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的标记限制。从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。在这种情况下访问语言模型时，请确保有适当的错误处理。
按照发布扩展中描述的方式上传到市场。

12/11/2024