언어 모델 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를 채팅 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에 업로드합니다.