Introduzione a AI Toolkit for Visual Studio Code

AI Toolkit for VS Code (AI Toolkit) è un'estensione VS Code che consente di scaricare, testare, ottimizzare e distribuire modelli di intelligenza artificiale con le app o nel cloud. Per altre informazioni, vedere panoramica di AI Toolkit.

Nota

La documentazione e le esercitazioni aggiuntive per AI Toolkit for VS Code sono disponibili nella VS Code documentazione: AI Toolkit for Visual Studio Code. Sono disponibili indicazioni su Playground, sull'uso di modelli di intelligenza artificiale, sull'ottimizzazione dei modelli locali e basati sul cloud e altro ancora.

In questo articolo si apprenderà come:

• Installare AI Toolkit per VS Code
• Scaricare un modello dal catalogo
• Eseguire il modello in locale usando il playground
• Integrare un modello di intelligenza artificiale nell'applicazione usando REST o il runtime ONNX

Prerequisiti

• VS Code deve essere installato. Per altre informazioni, vedere VS Codee iniziare a usare VS Code.

Quando si usano le funzionalità di intelligenza artificiale, è consigliabile esaminare: Sviluppo di applicazioni e funzionalità di intelligenza artificiale responsabile in Windows.

Installa

AI Toolkit è disponibile in Visual Studio Marketplace e può essere installato come qualsiasi altra VS Code estensione. Se non si ha familiarità con l'installazione VS Code delle estensioni, seguire questa procedura:

1. Nella barra delle attività in VS Code selezionare Estensioni
2. Nella barra di ricerca estensioni digitare "AI Toolkit"
3. Selezionare "AI Toolkit for Visual Studio code"
4. Selezionare Installa

Dopo aver installato l'estensione, l'icona di AI Toolkit verrà visualizzata nella barra delle attività.

Scaricare un modello dal catalogo

La barra laterale principale di AI Toolkit è organizzata in Modelli personali, Catalogo, Strumenti, e Guida e Feedback. Le funzionalità Playground, esecuzione massiva, Valutazionee Ottimizzazione sono disponibili nella sezione Strumenti. Per iniziare, selezionare Modelli dalla sezione Catalogo per aprire la finestra Catalogo Modelli.

È possibile usare i filtri nella parte superiore del catalogo per filtrare in base a Ospitato da, Editore, Attivitàe Tipo di modello. È anche disponibile un interruttore di supporto Fine-Tuning che è possibile attivare per visualizzare solo i modelli che possono essere ottimizzati.

Suggerimento

Il filtro tipo di modello consente di visualizzare solo i modelli che si eseguono localmente nella CPU, GPU o NPU, o modelli che supportano solo accesso remoto. Per ottimizzare le prestazioni nei dispositivi con almeno una GPU, selezionare il tipo di modello Esecuzione locale conGPU. Questo aiuta a trovare un modello ottimizzato per l'acceleratore DirectML .

Per verificare se nel dispositivo Windows è presente una GPU, aprire Gestione attività e quindi selezionare la scheda Prestazioni . Se sono presenti GPU, queste verranno elencate in nomi come "GPU 0" o "GPU 1".

Nota

Per i PC Copilot+ con un'unità di elaborazione neurale (NPU), è possibile selezionare i modelli ottimizzati per l'acceleratore NPU. Il modello Deepseek R1 Distilled è ottimizzato per la NPU ed è disponibile per il download su PC Copilot+ alimentati da Snapdragon che eseguono Windows 11. Per ulteriori informazioni, vedere Esecuzione di modelli Distilled DeepSeek R1 in locale su PC Copilot+, basati su Windows AI Foundry.

I modelli seguenti sono attualmente disponibili per i dispositivi Windows con una o più GPU:

• Mistral 7B (DirectML - Piccolo, Veloce)
• Phi 3 Mini 4K (DirectML - Piccolo, Veloce)
• Phi 3 Mini 128K (DirectML - Piccolo, Veloce)

Selezionare il modello Phi 3 Mini 4K e fare clic su Scarica:

Nota

Il modello Phi 3 Mini 4K è di circa 2 GB-3 GB. A seconda della velocità di rete, il download potrebbe richiedere alcuni minuti.

Eseguire il modello nel playground

Dopo aver scaricato il modello, verrà visualizzato nella sezione I miei modelli sotto Modelli locali. Fare clic con il pulsante destro del mouse sul modello e scegliere Carica in Playground dal menu contestuale:

Nell'interfaccia della chat del playground immettere il messaggio seguente seguito dal tasto INVIO :

Verrà visualizzata la risposta del modello trasmessa di nuovo all'utente:

Avviso

Se non si dispone di una GPU disponibile nel dispositivo, ma è stato selezionato il modello Phi-3-mini-4k-directml-int4-awq-block-128-onnx, la risposta del modello sarà molto lenta. È invece necessario scaricare la versione ottimizzata per la CPU: Phi-3-mini-4k-cpu-int4-rtn-block-32-acc-level-4-onnx.

È anche possibile modificare:

• Istruzioni di contesto: aiutare il modello a comprendere l'immagine più ampia della richiesta. Potrebbe trattarsi di informazioni di base, esempi/dimostrazioni di ciò che si desidera o spiegare lo scopo dell'attività.
• Parametri di inferenza:
  • Lunghezza massima della risposta: il numero massimo di token restituiti dal modello.
  • Temperatura: la temperatura del modello è un parametro che controlla la modalità di output casuale di un modello linguistico. Una temperatura più elevata significa che il modello assume più rischi, offrendo una combinazione diversificata di parole. D'altra parte, una temperatura inferiore rende il modello giocare al sicuro, in modo da rimanere più concentrati e prevedibili risposte.
  • P superiore: noto anche come campionamento del nucleo, è un'impostazione che controlla il numero di parole o frasi possibili che il modello linguistico prende in considerazione quando si stima la parola successiva
  • Penalità di frequenza: questo parametro influisce sulla frequenza con cui il modello ripete parole o frasi nell'output. Maggiore è il valore (più vicino a 1,0) incoraggia il modello a evitare di ripetere parole o frasi.
  • Penalità di presenza: questo parametro viene usato nei modelli di intelligenza artificiale generativi per incoraggiare la diversità e la specificità nel testo generato. Un valore più alto (più vicino a 1,0) incoraggia il modello ad includere token più nuovi e diversificati. Un valore inferiore è più probabile che il modello generi frasi comuni o cliché.

Integrare un modello di intelligenza artificiale nell'applicazione

Esistono due opzioni per integrare il modello nell'applicazione:

1. AI Toolkit include un REST Web API locale che usa il formato di completamento della chat OpenAI. In questo modo è possibile testare l'applicazione in locale, usando l'endpoint http://127.0.0.1:5272/v1/chat/completions , senza dover fare affidamento su un servizio modello di intelligenza artificiale cloud. Usare questa opzione se si intende passare a un endpoint cloud nell'ambiente di produzione. È possibile usare le librerie client OpenAI per connettersi al server Web.
2. Uso del runtime ONNX. Usare questa opzione se si intende spedire il modello con l'applicazione con inferenza nel dispositivo.

Server Web DELL'API locale REST

Il server Web API locale REST consente di compilare e testare l'applicazione in locale senza dover fare affidamento su un servizio modello di intelligenza artificiale cloud. È possibile interagire con il server Web usando RESTo con una libreria client OpenAI:

REST

Ecco un corpo di esempio per la REST richiesta:

{
    "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
}'

Nota

Potrebbe essere necessario aggiornare il campo del modello con il nome del modello scaricato.

È possibile testare l'endpoint REST usando uno strumento API come Postman o l'utilità CURL:

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

Pitone

Installare la libreria Python OpenAI:

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#

Aggiungere la libreria client OpenAI di Azure per .NET al progetto usando NuGet:

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

Aggiungere un file C# denominato OverridePolicy.cs al progetto e incollare il codice seguente:

// 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);
    }
}

Incollare quindi il codice seguente nel file 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);
}

Nota

Se è stata scaricata la versione della CPU del modello Phi3, è necessario aggiornare il campo del modello a Phi-3-mini-4k-cpu-int4-rtn-block-32-acc-level-4-onnx.

Runtime ONNX

L'API di generazione del runtime ONNX fornisce il ciclo di intelligenza artificiale generativo per i modelli ONNX, inclusa l'inferenza con ONNX Runtime, l'elaborazione dei logits, la ricerca e il campionamento e la gestione della cache KV. È possibile chiamare un metodo di alto livello generate() o eseguire ogni iterazione del modello in un ciclo, generando un token alla volta e facoltativamente aggiornando i parametri di generazione all'interno del ciclo.

Ha il supporto per la ricerca greedy/beam e TopP, il campionamento TopK per generare sequenze di token e l'elaborazione predefinita dei logits come sanzioni di ripetizione. Il codice seguente è un esempio di come è possibile sfruttare il runtime ONNX nelle applicazioni.

REST

Fare riferimento all'esempio illustrato in REST Web DELL'API locale. Il server Web di AI Toolkit REST viene compilato usando il runtime ONNX.

Pitone

Installare Numpy:

pip install numpy

Installare quindi il pacchetto Python onNX Runtime nel progetto in base alla piattaforma e alla disponibilità della GPU:

Piattaforma	GPU disponibile	PyPI
Finestre	Sì (AMD, NVIDIA, Intel, Qualcomm, più altri supportati)	pip install --pre onnxruntime-genai-directml
Linux	Sì (Nvidia CUDA)	pip install --pre onnxruntime-genai-cuda --index-url=https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/onnxruntime-genai/pypi/simple/
Finestre Linux	NO	pip install --pre onnxruntime-genai

Suggerimento

È consigliabile installare pacchetti Python in un ambiente virtuale usando venv o conda.

Copiare e incollare quindi il codice seguente in un file Python denominato 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)

Per eseguire l'app Python, usare il codice seguente:

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

Nota

Il modello ai Toolkit memorizza nella cache i download in una cartella nascosta denominata .aitk nella directory utente. È necessario aggiornare il percorso usato per il --model parametro nel percorso della cartella contenente il file del modello ONNX. Ad esempio: ~/.aitk/models/microsoft/Phi-3-mini-4k-instruct-onnx/directml/Phi-3-mini-4k-directml-int4-awq-block-128-onnx/

C#

Installare il pacchetto NuGet del runtime ONNX nel progetto in base alla piattaforma e alla disponibilità della GPU:

Piattaforma	GPU disponibile	NuGet
Finestre	Sì (AMD, NVIDIA, Intel, Qualcomm, più altri supportati)	Microsoft.ML.OnnxRuntimeGenAI.DirectML
Linux	Sì (Nvidia CUDA)	Microsoft.ML.OnnxRuntimeGenai.Cuda
Finestre Linux	NO	Microsoft.ML.OnnxRuntimeGenAI

Copiare e incollare il codice seguente nel file 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();
}

Nota

Il modello ai Toolkit memorizza nella cache i download in una cartella nascosta denominata .aitk nella directory utente. Sarà necessario aggiornare modelPath nel codice il percorso della cartella contenente il file del modello ONNX. Ad esempio: ~/.aitk/models/microsoft/Phi-3-mini-4k-instruct-onnx/directml/Phi-3-mini-4k-directml-int4-awq-block-128-onnx/

Passaggio successivo

Ottimizzare un modello con AI Toolkit per VS Code