Introdução ao Kit de Ferramentas de IA do Visual Studio Code

O Kit de Ferramentas de IA do VS Code (Kit de Ferramentas de IA) é uma extensão do VS Code que permite fazer download, testar, ajustar e implantar modelos de IA com seus aplicativos ou na nuvem. Para obter mais informações, consulte Visão geral do Kit de Ferramentas de IA.

Observação

Documentação e tutoriais adicionais para o Kit de Ferramentas de IA para VS Code estão disponíveis na documentação do VS Code: Kit de Ferramentas de IA para Visual Studio Code. Você encontrará orientações sobre o Playground, como trabalhar com modelos de IA, ajustar modelos locais e baseados em nuvem e muito mais.

Neste artigo, você aprenderá a:

• Instalar o Kit de Ferramentas de IA do VS Code
• Baixar um modelo do catálogo
• Executar o modelo localmente usando o playground
• Integrar um modelo de IA em seu aplicativo usando REST ou o ONNX Runtime

Pré-requisitos

• VS Code deve ser instalado. Para obter mais informações, confira Download VS Code e Getting started with VS Code.

Ao utilizar recursos de IA, recomendamos que você examine: Desenvolvendo aplicativos e recursos de IA generativos responsáveis no Windows.

Instalar

O Kit de Ferramentas de IA está disponível no Visual Studio Marketplace e pode ser instalado como qualquer outra extensão do VS Code. Caso não saiba como instalar extensões do VS Code, siga estas etapas:

1. Na barra Atividades do VS Code, selecione Extensões
2. Na barra de pesquisa Extensões, digite "Kit de Ferramentas de IA"
3. Selecione o "Kit de Ferramentas de IA do Visual Studio Code"
4. Selecionar Instalar

Depois que a extensão for instalada, você verá o ícone do Kit de Ferramentas de IA aparecer na barra Atividades.

Baixar um modelo do catálogo

A barra lateral primária do Kit de Ferramentas de IA é organizada em My Models, Catalog, Toolse Help and Feedback. Os recursos Playground, Execução em Massa, Avaliação e Ajuste fino estão disponíveis na seção Ferramentas. Para começar, selecione Modelos na seção Catálogo para abrir a janela Catálogo de Modelos:

Você pode usar os filtros na parte superior do catálogo para filtrar por Hospedado por, Fornecedor, Tarefas e Tipo de modelo. Há também uma opção Suporte de Ajuste Fino que você pode ativar para mostrar somente os modelos que podem ser ajustados.

Dica

O filtro Tipo de modelo permite mostrar somente os modelos que serão executados localmente na CPU, GPU ou NPU ou modelos que suportam apenas Acesso remoto. Para obter desempenho otimizado em dispositivos que têm pelo menos uma GPU, selecione o tipo de modelo Execução local com GPU. Isso ajuda a encontrar um modelo otimizado para o acelerador DirectML.

Para verificar se você tem uma GPU no dispositivo Windows, abra o Gerenciador de Tarefas e selecione a guia Desempenho. Se você tiver GPUs, elas serão listadas com nomes como "GPU 0" ou "GPU 1".

Observação

Para computadores Copilot+ com uma NPU (Unidade de Processamento Neural), você pode selecionar modelos otimizados para o acelerador de NPU. O modelo Distilled do Deepseek R1 é otimizado para a NPU e está disponível para download em PCs Copilot+ equipados com Snapdragon com Windows 11. Para obter mais informações, consulte Executando modelos destilados de DeepSeek R1 localmente em PCs Copilot+, potencializados por Windows AI Foundry.

No momento, os seguintes modelos estão disponíveis para dispositivos Windows com uma ou mais GPUs:

• Mistral 7B (DirectML - Pequeno, Rápido)
• Phi 3 Mini 4K (DirectML - Pequeno, Rápido)
• Phi 3 Mini 128K (DirectML - Pequeno, Rápido)

Selecione o modelo Phi 3 Mini 4K e clique em Baixar:

Observação

O modelo Phi 3 Mini 4K tem aproximadamente 2 GB-3 GB de tamanho. Dependendo da velocidade da sua rede, o download pode demorar alguns minutos.

Executar o modelo no playground

Depois que o modelo for baixado, ele aparecerá na seção 'Meus Modelos' em 'Modelos Locais'. Clique com o botão direito do mouse no modelo e selecione Carregar no Playground no menu de contexto:

Na interface de bate-papo do playground, digite a seguinte mensagem seguida pela tecla Enter:

Você deve ver a resposta do modelo transmitida de volta para você:

Aviso

Se você não tiver uma GPU disponível em seu dispositivo, mas tiver selecionado o modelo Phi-3-mini-4k-directml-int4-awq-block-128-onnx, a resposta do modelo será muito lenta. Em vez disso, você deve baixar a versão otimizada para CPU: Phi-3-mini-4k-cpu-int4-rtn-block-32-acc-level-4-onnx.

Também é possível alterar:

• Instruções de contexto: ajude o modelo a entender o panorama geral da sua solicitação. Podem ser informações básicas, exemplos/demonstrações do que você quer ou explicações sobre o propósito da sua tarefa.
• Parâmetros de inferência:
  • Comprimento máximo da resposta: o número máximo de tokens que o modelo retornará.
  • Temperatura: a temperatura do modelo é um parâmetro que controla o quão aleatória é a saída de um modelo de linguagem. Uma temperatura mais alta significa que o modelo corre mais riscos, fornecendo uma mistura diversificada de palavras. Por outro lado, uma temperatura mais baixa faz com que o modelo seja mais seguro, aderindo a respostas mais focadas e previsíveis.
  • Top P: também conhecida como amostragem de núcleo, é uma configuração que controla quantas palavras ou frases possíveis o modelo de linguagem considera ao prever a próxima palavra
  • Penalidade de frequência: este parâmetro influencia a frequência com que o modelo repete palavras ou frases em sua saída. Quanto maior o valor (mais próximo de 1,0), o modelo evita a repetição de palavras ou frases.
  • Penalidade de presença: este parâmetro é usado em modelos de IA generativa para incentivar a diversidade e especificidade no texto gerado. Com um valor mais alto (mais próximo de 1,0) o modelo é incentivado a incluir tokens mais novos e diversos. Com um valor mais baixo, é mais provável que o modelo gere frases comuns ou clichês.

Integrar um modelo de IA ao aplicativo

Há duas opções de integrar o modelo ao seu aplicativo:

1. O Kit de Ferramentas de IA vem com um servidorREST Web de API local que usa o formato de conclusão de chat do OpenAI. Assim, você pode testar seu aplicativo localmente usando o ponto de extremidade http://127.0.0.1:5272/v1/chat/completions sem precisar de um serviço de modelo de IA na nuvem. Use essa opção se você pretende mudar para um ponto de extremidade na nuvem em produção. Você pode usar bibliotecas de cliente OpenAI para se conectar ao servidor Web.
2. Usar o ONNX Runtime. Use esta opção se pretende enviar o modelo com seu aplicativo com inferência no dispositivo.

Um servidor Web de API REST local

O servidor Web de API REST local permite criar e testar seu aplicativo localmente sem a necessidade de um serviço de modelo de IA na nuvem. Você pode interagir com o servidor Web usando REST, ou com uma biblioteca de cliente OpenAI:

REST

Veja um exemplo de corpo para sua solicitação REST:

{
    "model": "Phi-3-mini-4k-directml-int4-awq-block-128-onnx",
    "messages": [
        {
            "role": "user",
            "content": "what is the golden ratio?"
        }
    ],
    "temperature": 0.7,
    "top_p": 1,
    "top_k": 10,
    "max_tokens": 100,
    "stream": true
}'

Observação

Pode ser necessário atualizar o campo de modelo para o nome do modelo que você baixou.

Você pode testar o ponto de extremidade REST usando uma ferramenta API como Postman ou o utilitário CURL:

curl -vX POST http://127.0.0.1:5272/v1/chat/completions -H 'Content-Type: application/json' -d @body.json

Pitão

Instalar a biblioteca OpenAI Python:

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:5272/v1/",
    api_key="x" # required by API but not used
)

chat_completion = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "what is the golden ratio?",
        }
    ],
    model="Phi-3-mini-4k-directml-int4-awq-block-128-onnx",
)

print(chat_completion.choices[0].message.content)

C#

Adicione a biblioteca de clientes do Azure OpenAI para .NET ao seu projeto usando o NuGet:

dotnet add {project_name} package Azure.AI.OpenAI --version 1.0.0-beta.17

Adicione um arquivo C# chamado OverridePolicy.cs ao seu projeto e cole o seguinte código:

// OverridePolicy.cs
using Azure.Core.Pipeline;
using Azure.Core;

internal partial class OverrideRequestUriPolicy(Uri overrideUri)
    : HttpPipelineSynchronousPolicy
{
    private readonly Uri _overrideUri = overrideUri;

    public override void OnSendingRequest(HttpMessage message)
    {
        message.Request.Uri.Reset(_overrideUri);
    }
}

Em seguida, cole o código a seguir no arquivo Program.cs:

// Program.cs
using Azure.AI.OpenAI;

Uri localhostUri = new("http://localhost:5272/v1/chat/completions");

OpenAIClientOptions clientOptions = new();
clientOptions.AddPolicy(
    new OverrideRequestUriPolicy(localhostUri),
    Azure.Core.HttpPipelinePosition.BeforeTransport);
OpenAIClient client = new(openAIApiKey: "unused", clientOptions);

ChatCompletionsOptions options = new()
{
    DeploymentName = "Phi-3-mini-4k-directml-int4-awq-block-128-onnx",
    Messages =
    {
        new ChatRequestSystemMessage("You are a helpful assistant. Be brief and succinct."),
        new ChatRequestUserMessage("What is the golden ratio?"),
    }
};

StreamingResponse<StreamingChatCompletionsUpdate> streamingChatResponse
    = await client.GetChatCompletionsStreamingAsync(options);

await foreach (StreamingChatCompletionsUpdate chatChunk in streamingChatResponse)
{
    Console.Write(chatChunk.ContentUpdate);
}

Observação

Se você baixou a versão da CPU do modelo Phi3, será necessário atualizar o campo do modelo para Phi-3-mini-4k-cpu-int4-rtn-block-32-acc-level-4-onnx.

ONNX Runtime

A API Generate do ONNX Runtime fornece o loop de IA generativa para modelos ONNX, incluindo inferência com ONNX Runtime, processamento de logits, pesquisa e amostragem e gerenciamento de cache KV. Você pode chamar um método generate() de alto nível ou executar cada iteração do modelo em um loop, gerando um token de cada vez e, como alternativa, atualizando os parâmetros de geração dentro do loop.

Ele tem suporte para busca greedy/beam search e amostragem TopP, TopK para gerar sequências de token e processamento de logits interno, como penalidades de repetição. O código a seguir é um exemplo de como você pode aproveitar o runtime do ONNX em seus aplicativos.

REST

Confira o exemplo mostrado no servidor Web de API REST local. O servidor da Web do Kit de Ferramentas de IA do REST foi criado usando o ONNX Runtime.

Pitão

Instalar o Numpy:

pip install numpy

Em seguida, instale o pacote Python do ONNX Runtime em seu projeto de acordo com a plataforma e disponibilidade da GPU:

Plataforma	GPU disponível	PyPI
Windows	Sim (AMD, NVIDIA, Intel, Qualcomm, além de outras opções com suporte)	pip install --pre onnxruntime-genai-directml
Linux	Sim (Nvidia CUDA)	pip install --pre onnxruntime-genai-cuda --index-url=https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/onnxruntime-genai/pypi/simple/
Windows Linux	Não	pip install --pre onnxruntime-genai

Dica

Recomendamos instalar pacotes Python no ambiente virtual usando venv ou conda.

Em seguida, copie e cole o seguinte código no arquivo Python nomeado como app.py:

# app.py
import onnxruntime_genai as og
import argparse

def main(args):
    print("Loading model...")
    model = og.Model(f'{args.model}')
    print("Model loaded")
    tokenizer = og.Tokenizer(model)
    tokenizer_stream = tokenizer.create_stream()
    search_options = {
        'max_length': 2048
    }

    chat_template = '<|user|>\n{input} <|end|>\n<|assistant|>'

    # Keep asking for input prompts in a loop
    while True:
        text = input("Input: ")
    
        # If there is a chat template, use it
        prompt = f'{chat_template.format(input=text)}'

        input_tokens = tokenizer.encode(prompt)

        params = og.GeneratorParams(model)
        params.set_search_options(**search_options)
        params.input_ids = input_tokens
        
        generator = og.Generator(model, params)
        print("\nOutput: ", end='', flush=True)
        while not generator.is_done():
            generator.compute_logits()
            generator.generate_next_token()
            new_token = generator.get_next_tokens()[0]
            print(tokenizer_stream.decode(new_token), end='', flush=True)
              
        print()
        print()

        # Delete the generator to free the captured graph for the next generator, if graph capture is enabled
        del generator


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument('-m', '--model', type=str, required=True, help='Onnx model folder path (must contain config.json and model.onnx)')
    args = parser.parse_args()
    main(args)

Para executar o aplicativo Python a seguir use o código a seguir:

python app.py --model ~/.aitk/models/{path_to_folder_containing_onnx_file}

Observação

O Kit de Ferramentas de IA armazena em cache os modelos baixados em uma pasta oculta nomeada .aitk no diretório do usuário. Você precisará atualizar o caminho usado para o parâmetro --model para o local da pasta que contém o arquivo de modelo ONNX. Por exemplo ~/.aitk/models/microsoft/Phi-3-mini-4k-instruct-onnx/directml/Phi-3-mini-4k-directml-int4-awq-block-128-onnx/

C#

Instale o pacote NuGet do ONNX Runtime em seu projeto de acordo com a plataforma e disponibilidade da GPU:

Plataforma	GPU disponível	Nuget
Windows	Sim (AMD, NVIDIA, Intel, Qualcomm, além de outras opções com suporte)	Microsoft.ML.OnnxRuntimeGenAI.DirectML
Linux	Sim (Nvidia CUDA)	Microsoft.ML.OnnxRuntimeGenAI.Cuda
Windows Linux	Não	Microsoft.ML.OnnxRuntimeGenAI

Copie e cole o código a seguir no arquivo C#:

using Microsoft.ML.OnnxRuntimeGenAI;

// update user_name and path placeholders
string modelPath = "C:\\Users\\{user_name}\\.aitk\\models\\{path}"; 
Console.Write("Loading model from " + modelPath + "...");
using Model model = new(modelPath);
Console.Write("Done\n");
using Tokenizer tokenizer = new(model);
using TokenizerStream tokenizerStream = tokenizer.CreateStream();

while (true)
{
    Console.Write("User:");
   
    string? input = Console.ReadLine();
    string prompt = "<|user|>\n" + input + "<|end|>\n<|assistant|>";

    var sequences = tokenizer.Encode(prompt);

    using GeneratorParams generatorParams = new GeneratorParams(model);
    generatorParams.SetSearchOption("max_length", 200);
    generatorParams.SetInputSequences(sequences);

    Console.Out.Write("\nAI:");
    using Generator generator = new(model, generatorParams);
    while (!generator.IsDone())
    { 
        generator.ComputeLogits();
        generator.GenerateNextToken();
        Console.Out.Write(tokenizerStream.Decode(generator.GetSequence(0)[^1]));
        Console.Out.Flush();
    }
    Console.WriteLine();
}

Observação

O Kit de Ferramenta de IA armazena em cache os modelos baixados em uma pasta oculta nomeada .aitk no diretório do usuário. Você precisará atualizar o modelPath no código para o local da pasta que contém o arquivo de modelo ONNX. Por exemplo ~/.aitk/models/microsoft/Phi-3-mini-4k-instruct-onnx/directml/Phi-3-mini-4k-directml-int4-awq-block-128-onnx/

Próxima Etapa

Ajustar um modelo com o Kit de Ferramentas de IA do VS Code