语言模型 API

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

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

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

1. 构建语言模型提示
2. 发送语言模型请求
3. 解释回应

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

要开始，您可以探索聊天扩展示例。

构建语言模型提示

要与语言模型互动，扩展程序应首先设计提示，然后向语言模型发送请求。您可以使用提示向语言模型提供有关您使用模型的广泛任务的说明。提示还可以定义用户消息的解释上下文。

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

• 用户 - 用于提供说明和用户请求
• 助手 - 用于将以前语言模型的响应历史作为上下文添加到提示中

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

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

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

你可以使用提示-tsx如果你希望对语言模型提示的构成有更多控制，可以使用这个库。例如，该库可以帮助动态调整提示的长度以适应每个语言模型的上下文Windows大小。了解更多关于@vscode/prompt-tsx 或者探索 聊天扩展示例 以开始。

要了解更多关于提示工程的概念，我们建议阅读OpenAI的优秀提示工程指南。

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

使用语言模型聊天消息类

语言模型 API 提供语言模型聊天消息类用于表示和创建聊天消息。你可以使用语言模型聊天消息.用户或语言模型聊天消息.助手方法分别用于创建用户消息或助手消息。

在下面的示例中，第一条消息为提示提供了上下文：

• 模型在其回复中使用的人格（在这种情况下，是一只猫）
• 生成响应时模型应遵循的规则（在这种情况下，以使用猫隐喻来以有趣的方式解释计算机科学概念）

第二个消息则提供了用户的具体请求或指令。它根据第一个消息提供的上下文确定要完成的具体任务。

const craftedPrompt = [
  vscode.LanguageModelChatMessage.User(
    '你是只猫！像猫一样仔细且逐步思考。你的工作是以猫的有趣方式解释计算机科学概念，使用猫的比喻。始终在回应中说明你在解释什么概念。始终包含代码示例。'
  ),
  vscode.LanguageModelChatMessage.User('我想了解递归')
];

发送语言模型请求

一旦你构建了语言模型的提示，你首先选择要使用的语言模型选择聊天模型方法。此方法返回符合指定条件的语言模型数组。如果您正在实现聊天参与者，我们建议您使用传递的模型而不是使用此方法。请求在你的聊天请求处理程序中处理对象。这确保了你的扩展尊重用户在聊天模型下拉菜单中选择的模型。然后，你通过使用发送请求方法。

要选择语言模型，您可以指定以下属性：供应商，身份证，家庭，或版本。使用这些属性可以广泛匹配某个供应商或系列的所有型号，或者通过其ID选择一个特定型号。在API参考中了解更多关于这些属性的信息。

注意：目前，gpt-4o，gpt-4o迷你，输入：o1，o1-迷你，克劳德-3.5-十四行诗对语言模型家族提供支持。如果您不确定使用哪个模型，我们建议gpt-4o由于其性能和质量。为了直接在编辑器中进行交互，我们推荐gpt-4o迷你因为它表现出色。

如果没有符合指定条件的模型，则选择聊天模型方法返回一个空数组。您的扩展必须适当地处理此情况。

以下示例展示了如何选择所有Copilot型号，无论家庭或版本：

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

// 没有可用的模型
如果 (模型.长度 === 0) {
  // 待办事项：处理没有可用模型的情况
}

重要：Copilot 的语言模型在扩展使用之前需要用户的同意。同意是通过一个身份验证对话框实现的。因此，选择聊天模型应该作为用户发起的操作的一部分被调用，例如命令。

选择一个模型后，您可以通过调用发送请求给语言模型发送请求 在模型实例上调用方法。您传递之前精心制作的提示，以及任何附加选项和取消令牌。

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

以下代码片段展示了如何进行语言模型请求：

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("对不起，我只能解释计算机科学概念。")
      );
    }
  } else {
    // 添加其他错误处理逻辑
    throw err;
  }
}

解释回应

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

响应语言模型聊天响应) 语言模型 API 基于流，这使您能够提供流畅的用户体验。例如，当您将 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.```plaintext
文档.行At(文本编辑器.文档.行数 - 1);
        const position = new vscode.Position(最后一行.行号, 最后一行.文本.长度);
        编辑.插入(position, (<错误>err).消息);
      });
    }
  }
);
```

考虑事项

型号可用性

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

选择合适的模型

扩展作者可以选择哪个模型最适合他们的扩展。我们建议使用gpt-4o其性能和质量。要获取所有可用型号的完整列表，您可以使用此代码片段：

常量 所有模型 = 等待 vscode.语言模型.选择聊天模型(模型选择器);

速率限制

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

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

测试您的扩展

语言模型 API 返回的响应是不确定的，这意味着对于相同的请求，您可能会得到不同的响应。这种行为在测试您的扩展时可能会带来挑战。

扩展用于构建提示和解释语言模型响应的部分是确定性的，因此可以在不使用实际语言模型的情况下进行单元测试。然而，与语言模型互动并获取其响应是不确定性的，无法轻松测试。考虑以模块化的方式设计您的扩展代码，以便您可以对可以测试的特定部分进行单元测试。

发布您的扩展

一旦你创建了你的AI扩展，你就可以将你的扩展发布到Visual Studio Marketplace：

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

相关内容

• 语言模型 API 参考
• 了解更多关于 @vscode/prompt-tsx 的信息
• 构建 VS Code 聊天扩展