Language Model API
Die Language Model API ermöglicht Ihnen, die Sprachmodelle zu nutzen und KI-gestützte Funktionen sowie Verarbeitung natürlicher Sprache in Ihre Visual Studio Code-Erweiterung zu integrieren.
Sie können die Language Model API in verschiedenen Arten von Erweiterungen verwenden. Ein typischer Anwendungsfall für diese API sind Chat-Erweiterungen, bei denen Sie ein Sprachmodell verwenden, um die Anfrage des Benutzers zu interpretieren und eine Antwort zu liefern. Die Verwendung der Language Model API ist jedoch nicht auf dieses Szenario beschränkt. Sie könnten ein Sprachmodell in einer Sprach- oder Debugger-Erweiterung verwenden oder als Teil eines Befehls oder einer Aufgabe in einer benutzerdefinierten Erweiterung. Zum Beispiel könnte die Rust-Erweiterung das Sprachmodell verwenden, um Standardnamen anzubieten und so die Umbenennung zu verbessern.
Der Prozess zur Nutzung der Language Model API umfasst die folgenden Schritte:
- Erstellung des Sprachmodell-Prompts
- Senden der Anfrage an das Sprachmodell
- Interpretation der Antwort
Die folgenden Abschnitte bieten weitere Details zur Implementierung dieser Schritte in Ihrer Erweiterung.
Um loszulegen, können Sie das Chat-Erweiterungsbeispiel erkunden.
Erstellung des Sprachmodell-Prompts
Um mit einem Sprachmodell zu interagieren, sollten Erweiterungen zuerst ihren Prompt erstellen und dann eine Anfrage an das Sprachmodell senden. Sie können Prompts verwenden, um dem Sprachmodell Anweisungen zur allgemeinen Aufgabe zu geben, für die Sie das Modell verwenden. Prompts können auch den Kontext definieren, in dem Benutzernachrichten interpretiert werden.
Die Language Model API unterstützt zwei Arten von Nachrichten beim Erstellen des Sprachmodell-Prompts:
- Benutzer – wird für Anweisungen und die Anfrage des Benutzers verwendet
- Assistent – wird für die Aufnahme des Verlaufs früherer Sprachmodellantworten als Kontext zum Prompt verwendet
Hinweis: Derzeit unterstützt die Language Model API die Verwendung von Systemnachrichten nicht.
Sie können zwei Ansätze zur Erstellung des Sprachmodell-Prompts verwenden:
LanguageModelChatMessage– erstellen Sie den Prompt, indem Sie eine oder mehrere Nachrichten als Strings angeben. Diesen Ansatz können Sie verwenden, wenn Sie gerade erst mit der Language Model API beginnen.@vscode/prompt-tsx– deklarieren Sie den Prompt mithilfe der TSX-Syntax.
Sie können die Bibliothek prompt-tsx verwenden, wenn Sie mehr Kontrolle darüber wünschen, wie der Sprachmodell-Prompt zusammengestellt wird. Die Bibliothek kann beispielsweise dabei helfen, die Länge des Prompts dynamisch an das Kontextfenster jedes Sprachmodells anzupassen. Erfahren Sie mehr über @vscode/prompt-tsx oder erkunden Sie das Chat-Erweiterungsbeispiel, um loszulegen.
Um mehr über die Konzepte des Prompt Engineering zu erfahren, empfehlen wir Ihnen, die ausgezeichneten Prompt Engineering Richtlinien von OpenAI zu lesen.
Tipp: Nutzen Sie die umfangreiche VS Code Extension API, um den relevantesten Kontext zu erhalten und ihn in Ihren Prompt aufzunehmen. Zum Beispiel, um den Inhalt der aktiven Datei im Editor einzufügen.
Verwenden Sie die Klasse LanguageModelChatMessage
Die Language Model API stellt die Klasse LanguageModelChatMessage zur Darstellung und Erstellung von Chatnachrichten bereit. Sie können die Methoden LanguageModelChatMessage.User oder LanguageModelChatMessage.Assistant verwenden, um Benutzer- bzw. Assistentennachrichten zu erstellen.
Im folgenden Beispiel liefert die erste Nachricht den Kontext für den Prompt.
- Die vom Modell in seinen Antworten verwendete Persona (in diesem Fall eine Katze)
- Die Regeln, die das Modell bei der Generierung von Antworten befolgen soll (in diesem Fall, die Erklärung von Informatikkonzepten auf lustige Weise unter Verwendung von Katzenmetaphern)
Die zweite Nachricht liefert dann die spezifische Anfrage oder Anweisung des Benutzers. Sie bestimmt die spezifische Aufgabe, die unter Berücksichtigung des durch die erste Nachricht bereitgestellten Kontexts ausgeführt werden soll.
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')
];
Senden der Anfrage an das Sprachmodell
Nachdem Sie den Prompt für das Sprachmodell erstellt haben, wählen Sie zuerst das Sprachmodell aus, das Sie verwenden möchten, mit der Methode selectChatModels. Diese Methode gibt ein Array von Sprachmodellen zurück, die den angegebenen Kriterien entsprechen. Wenn Sie einen Chat-Teilnehmer implementieren, empfehlen wir, stattdessen das Modell zu verwenden, das als Teil des request-Objekts in Ihrem Chat-Anforderungshandler übergeben wird. Dies stellt sicher, dass Ihre Erweiterung das vom Benutzer in der Chat-Modell-Dropdown ausgewählte Modell berücksichtigt. Senden Sie dann die Anfrage an das Sprachmodell mit der Methode sendRequest.
Um das Sprachmodell auszuwählen, können Sie die folgenden Eigenschaften angeben: vendor, id, family oder version. Verwenden Sie diese Eigenschaften, um entweder alle Modelle eines bestimmten Anbieters oder einer bestimmten Familie allgemein abzugleichen oder um ein bestimmtes Modell anhand seiner ID auszuwählen. Erfahren Sie mehr über diese Eigenschaften in der API-Referenz.
Hinweis: Derzeit werden
gpt-4o,gpt-4o-mini,o1,o1-miniundclaude-3.5-sonnetfür die Sprachmodellfamilie unterstützt. Wenn Sie unsicher sind, welches Modell Sie verwenden sollen, empfehlen wirgpt-4oaufgrund seiner Leistung und Qualität. Für Interaktionen direkt im Editor empfehlen wirgpt-4o-miniaufgrund seiner Leistung.
Wenn keine Modelle den angegebenen Kriterien entsprechen, gibt die Methode selectChatModels ein leeres Array zurück. Ihre Erweiterung muss diesen Fall angemessen behandeln.
Das folgende Beispiel zeigt, wie alle Copilot-Modelle ausgewählt werden, unabhängig von Familie oder Version.
const models = await vscode.lm.selectChatModels({
vendor: 'copilot'
});
// No models available
if (models.length === 0) {
// TODO: handle the case when no models are available
}
Wichtig: Die Sprachmodelle von Copilot erfordern die Zustimmung des Benutzers, bevor eine Erweiterung sie verwenden kann. Die Zustimmung wird als Authentifizierungsdialog implementiert. Aus diesem Grund sollte
selectChatModelsim Rahmen einer benutzerinitiierten Aktion aufgerufen werden, z. B. einem Befehl.
Nachdem Sie ein Modell ausgewählt haben, können Sie eine Anfrage an das Sprachmodell senden, indem Sie die Methode sendRequest für die Modellinstanz aufrufen. Sie übergeben den zuvor erstellten Prompt zusammen mit allen zusätzlichen Optionen und einem Abbruch-Token.
Wenn Sie eine Anfrage an die Language Model API stellen, kann die Anfrage fehlschlagen. Zum Beispiel, weil das Modell nicht existiert, der Benutzer der Verwendung der Language Model API nicht zugestimmt hat oder weil Kontingentlimits überschritten wurden. Verwenden Sie LanguageModelError, um zwischen verschiedenen Fehlertypen zu unterscheiden.
Der folgende Codeausschnitt zeigt, wie eine Anfrage an ein Sprachmodell gestellt wird.
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;
}
}
Interpretation der Antwort
Nachdem Sie die Anfrage gesendet haben, müssen Sie die Antwort von der Language Model API verarbeiten. Je nach Ihrem Anwendungsfall können Sie die Antwort direkt an den Benutzer weiterleiten oder die Antwort interpretieren und zusätzliche Logik ausführen.
Die Antwort (LanguageModelChatResponse) von der Language Model API ist Streaming-basiert, was Ihnen eine reibungslose Benutzererfahrung ermöglicht. Zum Beispiel durch kontinuierliche Meldung von Ergebnissen und Fortschritten, wenn Sie die API in Kombination mit der Chat API verwenden.
Beim Verarbeiten der Streaming-Antwort können Fehler auftreten, z. B. Netzwerkverbindungsprobleme. Stellen Sie sicher, dass Sie eine angemessene Fehlerbehandlung in Ihrem Code hinzufügen, um diese Fehler zu behandeln.
Der folgende Codeausschnitt zeigt, wie eine Erweiterung einen Befehl registrieren kann, der das Sprachmodell verwendet, um alle Variablennamen im aktiven Editor mit lustigen Katzennamen zu ändern. Beachten Sie, dass die Erweiterung den Code zur Erleichterung der Benutzererfahrung zurück an den Editor streamt.
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);
});
}
}
);
Überlegungen
Modellverfügbarkeit
Wir erwarten nicht, dass bestimmte Modelle für immer unterstützt werden. Wenn Sie ein Sprachmodell in Ihrer Erweiterung referenzieren, stellen Sie sicher, dass Sie einen "defensiven" Ansatz verfolgen, wenn Sie Anfragen an dieses Sprachmodell senden. Das bedeutet, dass Sie Fälle, in denen Sie keinen Zugriff auf ein bestimmtes Modell haben, ordnungsgemäß behandeln sollten.
Auswahl des geeigneten Modells
Erweiterungsautoren können wählen, welches Modell für ihre Erweiterung am besten geeignet ist. Wir empfehlen die Verwendung von gpt-4o aufgrund seiner Leistung und Qualität. Um eine vollständige Liste der verfügbaren Modelle zu erhalten, können Sie diesen Codeausschnitt verwenden.
const allModels = await vscode.lm.selectChatModels(MODEL_SELECTOR);
Das empfohlene GPT-4o-Modell hat ein Limit von 64K Tokens. Das von selectChatModels zurückgegebene Modellobjekt hat ein Attribut maxInputTokens, das das Token-Limit anzeigt. Diese Limits werden erweitert, wenn wir mehr darüber erfahren, wie Erweiterungen die Sprachmodelle verwenden.
Ratenbegrenzung
Erweiterungen sollten das Sprachmodell verantwortungsvoll nutzen und sich der Ratenbegrenzung bewusst sein. VS Code ist für den Benutzer transparent darüber, wie Erweiterungen Sprachmodelle verwenden und wie viele Anfragen jede Erweiterung sendet und wie sich dies auf ihre jeweiligen Kontingente auswirkt.
Erweiterungen sollten die Language Model API nicht für Integrationstests verwenden, da diese ratenbeschränkt ist. Intern verwendet VS Code ein spezielles Nicht-Produktions-Sprachmodell für Simulationstests, und wir überlegen derzeit, wie wir eine skalierbare Sprachmodell-Testlösung für Erweiterungen bereitstellen können.
Testen Ihrer Erweiterung
Die Antworten, die die Language Model API liefert, sind nicht deterministisch, das heißt, Sie können für eine identische Anfrage eine andere Antwort erhalten. Dieses Verhalten kann das Testen Ihrer Erweiterung erschweren.
Der Teil der Erweiterung für die Erstellung von Prompts und die Interpretation von Sprachmodellantworten ist deterministisch und kann daher ohne ein tatsächliches Sprachmodell getestet werden. Die Interaktion und der Erhalt von Antworten vom Sprachmodell selbst sind jedoch nicht-deterministisch und können nicht einfach getestet werden. Erwägen Sie, den Erweiterungscode modular zu gestalten, um die spezifischen, testbaren Teile einheitlich testen zu können.
Veröffentlichung Ihrer Erweiterung
Sobald Sie Ihre KI-Erweiterung erstellt haben, können Sie Ihre Erweiterung im Visual Studio Marketplace veröffentlichen.
- Bevor Sie im VS Marketplace veröffentlichen, empfehlen wir Ihnen, die Microsoft AI Tools and Practices Guidelines zu lesen. Diese Richtlinien bieten Best Practices für die verantwortungsvolle Entwicklung und Nutzung von KI-Technologien.
- Durch die Veröffentlichung im VS Marketplace hält Ihre Erweiterung die GitHub Copilot Extensibility Acceptable Development and Use Policy ein.
- Wenn Ihre Erweiterung bereits andere Funktionalitäten als die Nutzung der Language Model API bereitstellt, empfehlen wir, keine Erweiterungsabhängigkeit von GitHub Copilot im Erweiterungsmanifest einzuführen. Dies stellt sicher, dass Benutzer der Erweiterung, die GitHub Copilot nicht verwenden, die Funktionalität ohne GitHub Copilot nutzen können. Stellen Sie sicher, dass für den Zugriff auf Sprachmodelle in diesem Fall eine angemessene Fehlerbehandlung vorhanden ist.
- Laden Sie in den Marketplace hoch, wie unter Publishing Extension beschrieben.