语言模型 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 令牌。来自 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。