Tutoriel : Créer un assistant conversation multitour avec Foundry Local

Dans ce tutoriel, vous créez un assistant de conversation interactif qui s’exécute entièrement sur votre appareil. L’assistant gère le contexte de conversation entre plusieurs échanges, ce qui vous rappelle ce que vous avez abordé précédemment dans la conversation. Vous utilisez le Kit de développement logiciel (SDK) Local Foundry pour sélectionner un modèle, définir une invite système et diffuser en continu le jeton de réponses par jeton.

Dans ce tutoriel, vous allez apprendre à :

  • Configurer un projet et installer le Kit de développement logiciel (SDK) Local Foundry
  • Parcourir le catalogue de modèles et sélectionner un modèle
  • Définir une invite système pour mettre en forme le comportement de l’Assistant
  • Implémenter une conversation à plusieurs tour avec l’historique des messages
  • Diffuser des réponses pour une expérience réactive
  • Nettoyer les ressources lorsque la conversation se termine

Prerequisites

  • Un ordinateur Windows, macOS ou Linux avec au moins 8 Go de RAM.

Référentiel d’exemples

Vous trouverez l’intégralité du code d’exemple de cet article dans le dépôt GitHub des exemples Foundry. Pour cloner le référentiel et accéder à l’exemple, utilisez :

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/csharp/foundry-local/tutorial-chat-assistant

Installer des packages

dotnet add package Microsoft.AI.Foundry.Local
dotnet add package OpenAI

Les exemples C# dans le référentiel GitHub sont des projets préconfigurés. Si vous développez ex nihilo, vous devez lire la référence de Foundry Local SDK pour plus d’informations sur la configuration de votre projet C# avec Foundry Local.

Parcourir le catalogue et sélectionner un modèle

Le SDK Local Foundry fournit un catalogue de modèles qui répertorie tous les modèles disponibles. Dans cette étape, vous initialisez le Kit de développement logiciel (SDK) et sélectionnez un modèle pour votre assistant conversation.

  • Ouvrez et remplacez Program.cs son contenu par le code suivant pour initialiser le Kit de développement logiciel (SDK) et sélectionnez un modèle :

    CancellationToken ct = CancellationToken.None;
    
    var config = new Configuration
    {
        AppName = "foundry_local_samples",
        LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information
    };
    
    using var loggerFactory = LoggerFactory.Create(builder =>
    {
        builder.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Information);
    });
    var logger = loggerFactory.CreateLogger<Program>();
    
    // Initialize the singleton instance
    await FoundryLocalManager.CreateAsync(config, logger);
    var mgr = FoundryLocalManager.Instance;
    
    // Download and register all execution providers.
    var currentEp = "";
    await mgr.DownloadAndRegisterEpsAsync((epName, percent) =>
    {
        if (epName != currentEp)
        {
            if (currentEp != "") Console.WriteLine();
            currentEp = epName;
        }
        Console.Write($"\r  {epName.PadRight(30)}  {percent,6:F1}%");
    });
    if (currentEp != "") Console.WriteLine();
    
    // Select and load a model from the catalog
    var catalog = await mgr.GetCatalogAsync();
    var model = await catalog.GetModelAsync("qwen2.5-0.5b")
        ?? throw new Exception("Model not found");
    
    await model.DownloadAsync(progress =>
    {
        Console.Write($"\rDownloading model: {progress:F2}%");
        if (progress >= 100f) Console.WriteLine();
    });
    
    await model.LoadAsync();
    Console.WriteLine("Model loaded and ready.");
    
    // Create one stateful native chat session for the conversation.
    using var chatSession = new ChatSession(model);
    chatSession.SetStreaming(true);
    

    La GetModelAsync méthode accepte un alias de modèle, qui est un nom convivial court qui correspond à un modèle spécifique dans le catalogue. La DownloadAsync méthode extrait les pondérations du modèle dans votre cache local et LoadAsync rend le modèle prêt pour l’inférence.

Définir une invite système

Une invite système définit la personnalité et le comportement de l’assistant. Il s’agit du premier message de l’historique des conversations et du modèle le référence tout au long de la conversation.

Ajoutez une invite système pour mettre en forme la façon dont l’Assistant répond :

// Start the conversation with a system prompt
var systemPrompt = "You are a helpful, friendly assistant. Keep your responses " +
                   "concise and conversational. If you don't know something, say so.";

Conseil / Astuce

Expérimentez avec différentes invites système pour modifier le comportement de l’assistant. Par exemple, vous pouvez lui demander de répondre en tant que pirate, enseignant ou expert de domaine.

Implémenter l'invite multitour

Un assistant de conversation doit maintenir le contexte entre plusieurs échanges. Pour ce faire, conservez la liste de tous les messages (système, utilisateur et Assistant) et envoyez la liste complète avec chaque requête. Le modèle utilise cet historique pour générer des réponses contextuellement pertinentes.

Ajoutez une boucle de conversation qui :

  • Lit l’entrée utilisateur à partir de la console.
  • Ajoute le message utilisateur à l’historique.
  • Envoie l’historique complet au modèle.
  • Ajoute la réponse de l’assistant à l’historique pour le tour suivant.
while (true)
{
    Console.Write("You: ");
    var userInput = Console.ReadLine();
    if (string.IsNullOrWhiteSpace(userInput) ||
        userInput.Equals("quit", StringComparison.OrdinalIgnoreCase) ||
        userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))
    {
        break;
    }

    using var request = new Request();
    if (chatSession.TurnCount == 0)
    {
        request.AddItem(MessageItem.System(systemPrompt));
    }
    request.AddItem(MessageItem.User(userInput));

    // Stream the response token by token
    Console.Write("Assistant: ");
    await using var streamingResponse = chatSession.ProcessStreamingRequestAsync(request, ct);
    await foreach (var item in streamingResponse)
    {
        using (item)
        {
            if (item is TextItem { Type: TextItemType.Default } text)
            {
                Console.Write(text.Text);
                Console.Out.Flush();
            }
        }
    }
    using var finalResponse = await streamingResponse.FinalResponse;
    Console.WriteLine("\n");
}

Chaque appel pour CompleteChatAsync reçoit l’historique complet des messages. Il s’agit de la façon dont le modèle « se souvient » des tours précédents : il ne stocke pas l’état entre les appels.

Ajouter des réponses en flux

La diffusion en continu imprime chaque jeton au fur et à mesure qu’il est généré, ce qui rend l’assistant plus réactif. Remplacez l’appel CompleteChatAsync par CompleteChatStreamingAsync le flux du jeton de réponse par jeton.

Mettez à jour la boucle de conversation pour utiliser la diffusion en continu :

// Stream the response token by token
Console.Write("Assistant: ");
await using var streamingResponse = chatSession.ProcessStreamingRequestAsync(request, ct);
await foreach (var item in streamingResponse)
{
    using (item)
    {
        if (item is TextItem { Type: TextItemType.Default } text)
        {
            Console.Write(text.Text);
            Console.Out.Flush();
        }
    }
}
using var finalResponse = await streamingResponse.FinalResponse;
Console.WriteLine("\n");

La version de diffusion en continu accumule la réponse complète afin qu’elle puisse être ajoutée à l’historique des conversations une fois le flux terminé.

Code complet

Remplacez le contenu de Program.cs par le code complet suivant :

using Microsoft.AI.Foundry.Local;
using Microsoft.Extensions.Logging;

CancellationToken ct = CancellationToken.None;

var config = new Configuration
{
    AppName = "foundry_local_samples",
    LogLevel = Microsoft.AI.Foundry.Local.LogLevel.Information
};

using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Information);
});
var logger = loggerFactory.CreateLogger<Program>();

// Initialize the singleton instance
await FoundryLocalManager.CreateAsync(config, logger);
var mgr = FoundryLocalManager.Instance;

// Download and register all execution providers.
var currentEp = "";
await mgr.DownloadAndRegisterEpsAsync((epName, percent) =>
{
    if (epName != currentEp)
    {
        if (currentEp != "") Console.WriteLine();
        currentEp = epName;
    }
    Console.Write($"\r  {epName.PadRight(30)}  {percent,6:F1}%");
});
if (currentEp != "") Console.WriteLine();

// Select and load a model from the catalog
var catalog = await mgr.GetCatalogAsync();
var model = await catalog.GetModelAsync("qwen2.5-0.5b")
    ?? throw new Exception("Model not found");

await model.DownloadAsync(progress =>
{
    Console.Write($"\rDownloading model: {progress:F2}%");
    if (progress >= 100f) Console.WriteLine();
});

await model.LoadAsync();
Console.WriteLine("Model loaded and ready.");

// Create one stateful native chat session for the conversation.
using var chatSession = new ChatSession(model);
chatSession.SetStreaming(true);

// Start the conversation with a system prompt
var systemPrompt = "You are a helpful, friendly assistant. Keep your responses " +
                   "concise and conversational. If you don't know something, say so.";

Console.WriteLine("\nChat assistant ready! Type 'quit' to exit.\n");

while (true)
{
    Console.Write("You: ");
    var userInput = Console.ReadLine();
    if (string.IsNullOrWhiteSpace(userInput) ||
        userInput.Equals("quit", StringComparison.OrdinalIgnoreCase) ||
        userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))
    {
        break;
    }

    using var request = new Request();
    if (chatSession.TurnCount == 0)
    {
        request.AddItem(MessageItem.System(systemPrompt));
    }
    request.AddItem(MessageItem.User(userInput));

    // Stream the response token by token
    Console.Write("Assistant: ");
    await using var streamingResponse = chatSession.ProcessStreamingRequestAsync(request, ct);
    await foreach (var item in streamingResponse)
    {
        using (item)
        {
            if (item is TextItem { Type: TextItemType.Default } text)
            {
                Console.Write(text.Text);
                Console.Out.Flush();
            }
        }
    }
    using var finalResponse = await streamingResponse.FinalResponse;
    Console.WriteLine("\n");
}

// Clean up - unload the model
chatSession.Dispose();
await model.UnloadAsync();
Console.WriteLine("Model unloaded. Goodbye!");

Exécutez l'assistant de chat :

dotnet run

Vous voyez un résultat similaire à :

Downloading model: 100.00%
Model loaded and ready.

Chat assistant ready! Type 'quit' to exit.

You: What is photosynthesis?
Assistant: Photosynthesis is the process plants use to convert sunlight, water, and carbon
dioxide into glucose and oxygen. It mainly happens in the leaves, inside structures
called chloroplasts.

You: Why is it important for other living things?
Assistant: It's essential because photosynthesis produces the oxygen that most living things
breathe. It also forms the base of the food chain — animals eat plants or eat other
animals that depend on plants for energy.

You: quit
Model unloaded. Goodbye!

Notez comment l’assistant mémorise le contexte des tours précédents , quand vous demandez « Pourquoi est-il important pour d’autres choses vivantes ? », il sait que vous parlez toujours de photosynthèse.

Référentiel d’exemples

L’exemple de code complet de cet article est disponible dans le référentiel foundry-samples GitHub. Pour cloner le référentiel et accéder à l’exemple d’utilisation :

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/javascript/foundry-local/tutorial-chat-assistant

Installer des packages

npm install foundry-local-sdk openai

Parcourir le catalogue et sélectionner un modèle

Le SDK Local Foundry fournit un catalogue de modèles qui répertorie tous les modèles disponibles. Dans cette étape, vous initialisez le Kit de développement logiciel (SDK) et sélectionnez un modèle pour votre assistant conversation.

  1. Créez un fichier appelé index.js.

  2. Ajoutez le code suivant pour initialiser le Kit de développement logiciel (SDK) et sélectionnez un modèle :

    // Initialize the Foundry Local SDK
    const manager = FoundryLocalManager.create({
        appName: 'foundry_local_samples',
        logLevel: 'info'
    });
    
    // Download and register all execution providers.
    let currentEp = '';
    await manager.downloadAndRegisterEps((epName, percent) => {
        if (epName !== currentEp) {
            if (currentEp !== '') process.stdout.write('\n');
            currentEp = epName;
        }
        process.stdout.write(`\r  ${epName.padEnd(30)}  ${percent.toFixed(1).padStart(5)}%`);
    });
    if (currentEp !== '') process.stdout.write('\n');
    
    // Select and load a model from the catalog
    const model = await manager.catalog.getModel('qwen2.5-0.5b');
    
    await model.download((progress) => {
        process.stdout.write(`\rDownloading model: ${progress.toFixed(2)}%`);
    });
    console.log('\nModel downloaded.');
    
    await model.load();
    console.log('Model loaded and ready.');
    
    // Create a stateful native chat session
    const chatSession = new ChatSession(model);
    chatSession.setOptions({
        search: { temperature: 0.7, maxOutputTokens: 512 }
    });
    

    La getModel méthode accepte un alias de modèle, qui est un nom convivial court qui correspond à un modèle spécifique dans le catalogue. La download méthode extrait les pondérations du modèle dans votre cache local et load rend le modèle prêt pour l’inférence.

Définir une invite système

Une invite système définit la personnalité et le comportement de l’assistant. Il s’agit du premier message de l’historique des conversations et du modèle le référence tout au long de la conversation.

Ajoutez une invite système pour mettre en forme la façon dont l’Assistant répond :

// Start the conversation with a system prompt
const systemPrompt =
    'You are a helpful, friendly assistant. Keep your responses ' +
    'concise and conversational. If you don\'t know something, say so.';
let firstTurn = true;

Conseil / Astuce

Expérimentez avec différentes invites système pour modifier le comportement de l’assistant. Par exemple, vous pouvez lui demander de répondre en tant que pirate, enseignant ou expert de domaine.

Implémenter l'invite multitour

Un assistant de conversation doit maintenir le contexte entre plusieurs échanges. Pour ce faire, conservez la liste de tous les messages (système, utilisateur et Assistant) et envoyez la liste complète avec chaque requête. Le modèle utilise cet historique pour générer des réponses contextuellement pertinentes.

Ajoutez une boucle de conversation qui :

  • Lit l’entrée utilisateur à partir de la console.
  • Ajoute le message utilisateur à l’historique.
  • Envoie l’historique complet au modèle.
  • Ajoute la réponse de l’assistant à l’historique pour le tour suivant.
while (true) {
    const userInput = await askQuestion('You: ');
    if (userInput.trim().toLowerCase() === 'quit' ||
        userInput.trim().toLowerCase() === 'exit') {
        break;
    }

    const request = new Request();
    if (firstTurn) {
        request.addItem(Item.systemMessage(systemPrompt));
        firstTurn = false;
    }
    request.addItem(Item.userMessage(userInput));

    // Stream the response token by token
    process.stdout.write('Assistant: ');
    const stream = chatSession.processStreamingRequest(request);
    for await (const item of stream) {
        if (item.type === 'text' && item.textType === 'default') {
            process.stdout.write(item.text);
        }
    }
    await stream.response;
    console.log('\n');
}

Chaque appel pour completeChat reçoit l’historique complet des messages. Il s’agit de la façon dont le modèle « se souvient » des tours précédents : il ne stocke pas l’état entre les appels.

Ajouter des réponses en flux

La diffusion en continu imprime chaque jeton au fur et à mesure qu’il est généré, ce qui rend l’assistant plus réactif. Remplacez l’appel completeChat par completeStreamingChat le flux du jeton de réponse par jeton.

Mettez à jour la boucle de conversation pour utiliser la diffusion en continu :

// Stream the response token by token
process.stdout.write('Assistant: ');
const stream = chatSession.processStreamingRequest(request);
for await (const item of stream) {
    if (item.type === 'text' && item.textType === 'default') {
        process.stdout.write(item.text);
    }
}
await stream.response;
console.log('\n');

La version de diffusion en continu accumule la réponse complète afin qu’elle puisse être ajoutée à l’historique des conversations une fois le flux terminé.

Code complet

Créez un fichier nommé index.js et ajoutez le code complet suivant :

import {
    ChatSession,
    FoundryLocalManager,
    Item,
    Request
} from 'foundry-local-sdk';
import * as readline from 'readline';

// Initialize the Foundry Local SDK
const manager = FoundryLocalManager.create({
    appName: 'foundry_local_samples',
    logLevel: 'info'
});

// Download and register all execution providers.
let currentEp = '';
await manager.downloadAndRegisterEps((epName, percent) => {
    if (epName !== currentEp) {
        if (currentEp !== '') process.stdout.write('\n');
        currentEp = epName;
    }
    process.stdout.write(`\r  ${epName.padEnd(30)}  ${percent.toFixed(1).padStart(5)}%`);
});
if (currentEp !== '') process.stdout.write('\n');

// Select and load a model from the catalog
const model = await manager.catalog.getModel('qwen2.5-0.5b');

await model.download((progress) => {
    process.stdout.write(`\rDownloading model: ${progress.toFixed(2)}%`);
});
console.log('\nModel downloaded.');

await model.load();
console.log('Model loaded and ready.');

// Create a stateful native chat session
const chatSession = new ChatSession(model);
chatSession.setOptions({
    search: { temperature: 0.7, maxOutputTokens: 512 }
});

// Start the conversation with a system prompt
const systemPrompt =
    'You are a helpful, friendly assistant. Keep your responses ' +
    'concise and conversational. If you don\'t know something, say so.';
let firstTurn = true;

// Set up readline for console input
const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout
});

const askQuestion = (prompt) => new Promise((resolve) => {
    if (rl.closed) return resolve('quit');
    const onClose = () => resolve('quit');
    rl.once('close', onClose);
    try {
        rl.question(prompt, (answer) => {
            rl.off('close', onClose);
            resolve(answer);
        });
    } catch {
        rl.off('close', onClose);
        resolve('quit');
    }
});

console.log('\nChat assistant ready! Type \'quit\' to exit.\n');

while (true) {
    const userInput = await askQuestion('You: ');
    if (userInput.trim().toLowerCase() === 'quit' ||
        userInput.trim().toLowerCase() === 'exit') {
        break;
    }

    const request = new Request();
    if (firstTurn) {
        request.addItem(Item.systemMessage(systemPrompt));
        firstTurn = false;
    }
    request.addItem(Item.userMessage(userInput));

    // Stream the response token by token
    process.stdout.write('Assistant: ');
    const stream = chatSession.processStreamingRequest(request);
    for await (const item of stream) {
        if (item.type === 'text' && item.textType === 'default') {
            process.stdout.write(item.text);
        }
    }
    await stream.response;
    console.log('\n');
}

// Clean up - unload the model
chatSession.dispose();
await model.unload();
console.log('Model unloaded. Goodbye!');
rl.close();

Exécutez l'assistant de chat :

node index.js

Vous voyez un résultat similaire à :

Downloading model: 100.00%
Model downloaded.
Model loaded and ready.

Chat assistant ready! Type 'quit' to exit.

You: What is photosynthesis?
Assistant: Photosynthesis is the process plants use to convert sunlight, water, and carbon
dioxide into glucose and oxygen. It mainly happens in the leaves, inside structures
called chloroplasts.

You: Why is it important for other living things?
Assistant: It's essential because photosynthesis produces the oxygen that most living things
breathe. It also forms the base of the food chain — animals eat plants or eat other
animals that depend on plants for energy.

You: quit
Model unloaded. Goodbye!

Notez comment l’assistant mémorise le contexte des tours précédents , quand vous demandez « Pourquoi est-il important pour d’autres choses vivantes ? », il sait que vous parlez toujours de photosynthèse.

Référentiel d’exemples

L’exemple de code complet de cet article est disponible dans le référentiel foundry-samples GitHub. Pour cloner le référentiel et accéder à l’exemple d’utilisation :

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/python/foundry-local/tutorial-chat-assistant

Installer des packages

pip install foundry-local-sdk openai

Parcourir le catalogue et sélectionner un modèle

Le SDK Local Foundry fournit un catalogue de modèles qui répertorie tous les modèles disponibles. Dans cette étape, vous initialisez le Kit de développement logiciel (SDK) et sélectionnez un modèle pour votre assistant conversation.

  1. Créez un fichier appelé main.py.

  2. Ajoutez le code suivant pour initialiser le Kit de développement logiciel (SDK) et sélectionnez un modèle :

    # Initialize the Foundry Local SDK
    config = Configuration(app_name="foundry_local_samples")
    FoundryLocalManager.initialize(config)
    manager = FoundryLocalManager.instance
    
    # Discover and register execution providers that are not already available.
    missing_eps = [ep.name for ep in manager.discover_eps() if not ep.is_registered]
    if missing_eps:
        manager.download_and_register_eps(missing_eps)
    
    # Select and load a model from the catalog.
    model = manager.catalog.get_model("qwen2.5-0.5b")
    if model is None:
        raise RuntimeError("Model 'qwen2.5-0.5b' was not found in the catalog.")
    if not model.is_cached:
        model.download(
            lambda progress: print(
                f"\rDownloading model: {progress:.2f}%", end="", flush=True
            )
        )
        print()
    model.load()
    print("Model loaded and ready.")
    

    La get_model méthode accepte un alias de modèle, qui est un nom convivial court qui correspond à un modèle spécifique dans le catalogue. La download méthode extrait les pondérations du modèle dans votre cache local et load rend le modèle prêt pour l’inférence.

Définir une invite système

Une invite système définit la personnalité et le comportement de l’assistant. Il s’agit du premier message de l’historique des conversations et du modèle le référence tout au long de la conversation.

Ajoutez une invite système pour mettre en forme la façon dont l’Assistant répond :

# Start the conversation with a system prompt.
system_prompt = (
    "You are a helpful, friendly assistant. Keep your responses "
    "concise and conversational. If you don't know something, say so."
)

Conseil / Astuce

Expérimentez avec différentes invites système pour modifier le comportement de l’assistant. Par exemple, vous pouvez lui demander de répondre en tant que pirate, enseignant ou expert de domaine.

Implémenter l'invite multitour

Un assistant de conversation doit maintenir le contexte entre plusieurs échanges. Pour ce faire, conservez la liste de tous les messages (système, utilisateur et Assistant) et envoyez la liste complète avec chaque requête. Le modèle utilise cet historique pour générer des réponses contextuellement pertinentes.

Ajoutez une boucle de conversation qui :

  • Lit l’entrée utilisateur à partir de la console.
  • Ajoute le message utilisateur à l’historique.
  • Envoie l’historique complet au modèle.
  • Ajoute la réponse de l’assistant à l’historique pour le tour suivant.
while True:
    user_input = input("You: ")
    if user_input.strip().lower() in ("quit", "exit"):
        break

    # The stateful session retains earlier turns automatically.
    with Request() as request:
        if first_turn:
            request.add_item(MessageItem.system(system_prompt))
            first_turn = False
        request.add_item(MessageItem.user(user_input))
        print("Assistant: ", end="", flush=True)
        with session.process_streaming_request(request) as stream:
            for item in stream:
                if (
                    isinstance(item, TextItem)
                    and item.type == TextItemType.DEFAULT
                ):
                    print(item.text, end="", flush=True)
        print("\n")

Chaque appel pour complete_chat reçoit l’historique complet des messages. Il s’agit de la façon dont le modèle « se souvient » des tours précédents : il ne stocke pas l’état entre les appels.

Ajouter des réponses en flux

La diffusion en continu imprime chaque jeton au fur et à mesure qu’il est généré, ce qui rend l’assistant plus réactif. Remplacez l’appel complete_chat par complete_streaming_chat le flux du jeton de réponse par jeton.

Mettez à jour la boucle de conversation pour utiliser la diffusion en continu :

# The stateful session retains earlier turns automatically.
with Request() as request:
    if first_turn:
        request.add_item(MessageItem.system(system_prompt))
        first_turn = False
    request.add_item(MessageItem.user(user_input))
    print("Assistant: ", end="", flush=True)
    with session.process_streaming_request(request) as stream:
        for item in stream:
            if (
                isinstance(item, TextItem)
                and item.type == TextItemType.DEFAULT
            ):
                print(item.text, end="", flush=True)
    print("\n")

La version de diffusion en continu accumule la réponse complète afin qu’elle puisse être ajoutée à l’historique des conversations une fois le flux terminé.

Code complet

Créez un fichier nommé main.py et ajoutez le code complet suivant :

from foundry_local_sdk import (
    ChatSession,
    Configuration,
    FoundryLocalManager,
    MessageItem,
    Request,
    RequestOptions,
    SearchOptions,
    TextItem,
    TextItemType,
)



def main():
    # Initialize the Foundry Local SDK
    config = Configuration(app_name="foundry_local_samples")
    FoundryLocalManager.initialize(config)
    manager = FoundryLocalManager.instance

    # Discover and register execution providers that are not already available.
    missing_eps = [ep.name for ep in manager.discover_eps() if not ep.is_registered]
    if missing_eps:
        manager.download_and_register_eps(missing_eps)

    # Select and load a model from the catalog.
    model = manager.catalog.get_model("qwen2.5-0.5b")
    if model is None:
        raise RuntimeError("Model 'qwen2.5-0.5b' was not found in the catalog.")
    if not model.is_cached:
        model.download(
            lambda progress: print(
                f"\rDownloading model: {progress:.2f}%", end="", flush=True
            )
        )
        print()
    model.load()
    print("Model loaded and ready.")

    try:
        # Start the conversation with a system prompt.
        system_prompt = (
            "You are a helpful, friendly assistant. Keep your responses "
            "concise and conversational. If you don't know something, say so."
        )

        print("\nChat assistant ready! Type 'quit' to exit.\n")

        with ChatSession(model) as session:
            session.set_options(
                RequestOptions(
                    search=SearchOptions(temperature=0.7, max_output_tokens=512)
                )
            )
            session.set_streaming(True)
            first_turn = True

            while True:
                user_input = input("You: ")
                if user_input.strip().lower() in ("quit", "exit"):
                    break

                # The stateful session retains earlier turns automatically.
                with Request() as request:
                    if first_turn:
                        request.add_item(MessageItem.system(system_prompt))
                        first_turn = False
                    request.add_item(MessageItem.user(user_input))
                    print("Assistant: ", end="", flush=True)
                    with session.process_streaming_request(request) as stream:
                        for item in stream:
                            if (
                                isinstance(item, TextItem)
                                and item.type == TextItemType.DEFAULT
                            ):
                                print(item.text, end="", flush=True)
                    print("\n")
    finally:
        # Clean up - unload the model
        if model.is_loaded:
            model.unload()
        manager.close()
        print("Model unloaded. Goodbye!")


if __name__ == "__main__":
    main()

Exécutez l'assistant de chat :

python main.py

Vous voyez un résultat similaire à :

Downloading model: 100.00%
Model loaded and ready.

Chat assistant ready! Type 'quit' to exit.

You: What is photosynthesis?
Assistant: Photosynthesis is the process plants use to convert sunlight, water, and carbon
dioxide into glucose and oxygen. It mainly happens in the leaves, inside structures
called chloroplasts.

You: Why is it important for other living things?
Assistant: It's essential because photosynthesis produces the oxygen that most living things
breathe. It also forms the base of the food chain — animals eat plants or eat other
animals that depend on plants for energy.

You: quit
Model unloaded. Goodbye!

Notez comment l’assistant mémorise le contexte des tours précédents , quand vous demandez « Pourquoi est-il important pour d’autres choses vivantes ? », il sait que vous parlez toujours de photosynthèse.

Référentiel d’exemples

L’exemple de code complet de cet article est disponible dans le référentiel foundry-samples GitHub. Pour cloner le référentiel et accéder à l’exemple d’utilisation :

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/rust/foundry-local/tutorial-chat-assistant

Installer des packages

cargo add foundry-local-sdk
cargo add tokio --features full
cargo add tokio-stream anyhow

Parcourir le catalogue et sélectionner un modèle

Le SDK Local Foundry fournit un catalogue de modèles qui répertorie tous les modèles disponibles. Dans cette étape, vous initialisez le Kit de développement logiciel (SDK) et sélectionnez un modèle pour votre assistant conversation.

  • Ouvrez et remplacez src/main.rs son contenu par le code suivant pour initialiser le Kit de développement logiciel (SDK) et sélectionnez un modèle :

    // Initialize the Foundry Local SDK
    let manager = FoundryLocalManager::create(FoundryLocalConfig::new("foundry_local_samples"))?;
    
    manager
        .download_and_register_eps_with_progress(None, {
            let mut current_ep = String::new();
            move |ep_name: &str, percent: f64| {
                if ep_name != current_ep {
                    if !current_ep.is_empty() {
                        println!();
                    }
                    current_ep = ep_name.to_string();
                }
                print!("\r  {ep_name:<30}  {percent:5.1}%");
                io::stdout().flush().ok();
            }
        })
        .await?;
    println!();
    
    let model = manager.catalog().get_model("qwen2.5-0.5b").await?;
    if !model.is_cached().await? {
        println!("Downloading model...");
        model
            .download(Some(|progress: f64| {
                print!("\r  {progress:.1}%");
                io::stdout().flush().ok();
            }))
            .await?;
        println!();
    }
    
    model.load().await?;
    let session = ChatSession::new(&model).await?;
    session
        .set_options(RequestOptions {
            search: SearchOptions {
                temperature: Some(0.7),
                max_output_tokens: Some(512),
                ..Default::default()
            },
            ..Default::default()
        })
        .await?;
    println!("Model loaded and ready.");
    

    La get_model méthode accepte un alias de modèle, qui est un nom convivial court qui correspond à un modèle spécifique dans le catalogue. La download méthode extrait les pondérations du modèle dans votre cache local et load rend le modèle prêt pour l’inférence.

Définir une invite système

Une invite système définit la personnalité et le comportement de l’assistant. Il s’agit du premier message de l’historique des conversations et du modèle le référence tout au long de la conversation.

Ajoutez une invite système pour mettre en forme la façon dont l’Assistant répond :

let system_prompt = "You are a helpful, friendly assistant. Keep your responses concise and \
                     conversational. If you don't know something, say so.";

Conseil / Astuce

Expérimentez avec différentes invites système pour modifier le comportement de l’assistant. Par exemple, vous pouvez lui demander de répondre en tant que pirate, enseignant ou expert de domaine.

Implémenter l'invite multitour

Un assistant de conversation doit maintenir le contexte entre plusieurs échanges. Pour ce faire, conservez un vecteur de tous les messages (système, utilisateur et Assistant) et envoyez la liste complète avec chaque requête. Le modèle utilise cet historique pour générer des réponses contextuellement pertinentes.

Ajoutez une boucle de conversation qui :

  • Lit l’entrée utilisateur à partir de la console.
  • Ajoute le message utilisateur à l’historique.
  • Envoie l’historique complet au modèle.
  • Ajoute la réponse de l’assistant à l’historique pour le tour suivant.
loop {
    print!("You: ");
    io::stdout().flush()?;

    let mut input = String::new();
    stdin.lock().read_line(&mut input)?;
    let input = input.trim();

    if input.eq_ignore_ascii_case("quit") || input.eq_ignore_ascii_case("exit") {
        break;
    }
    if input.is_empty() {
        continue;
    }

    let mut items = Vec::new();
    if session.turn_count() == 0 {
        items.push(Item::system_message(vec![Item::text(system_prompt)]));
    }
    items.push(Item::user_message(vec![Item::text(input)]));

    print!("Assistant: ");
    io::stdout().flush()?;
    let mut stream = session.process_streaming_request(Request::from_items(items));
    while let Some(item) = stream.next().await {
        if let Item::Text {
            text,
            kind: TextKind::Default,
        } = item?
        {
            print!("{text}");
            io::stdout().flush()?;
        }
    }
    println!("\n");
}

Chaque appel pour complete_chat reçoit l’historique complet des messages. Il s’agit de la façon dont le modèle « se souvient » des tours précédents : il ne stocke pas l’état entre les appels.

Ajouter des réponses en flux

La diffusion en continu imprime chaque jeton au fur et à mesure qu’il est généré, ce qui rend l’assistant plus réactif. Remplacez l’appel complete_chat par complete_streaming_chat le flux du jeton de réponse par jeton.

Mettez à jour la boucle de conversation pour utiliser la diffusion en continu :

print!("Assistant: ");
io::stdout().flush()?;
let mut stream = session.process_streaming_request(Request::from_items(items));
while let Some(item) = stream.next().await {
    if let Item::Text {
        text,
        kind: TextKind::Default,
    } = item?
    {
        print!("{text}");
        io::stdout().flush()?;
    }
}
println!("\n");

La version de diffusion en continu accumule la réponse complète afin qu’elle puisse être ajoutée à l’historique des conversations une fois le flux terminé.

Code complet

Remplacez le contenu de src/main.rs par le code complet suivant :

use foundry_local_sdk::{
    ChatSession, FoundryLocalConfig, FoundryLocalManager, Item, Request, RequestOptions,
    SearchOptions, TextKind,
};
use std::io::{self, BufRead, Write};
use tokio_stream::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the Foundry Local SDK
    let manager = FoundryLocalManager::create(FoundryLocalConfig::new("foundry_local_samples"))?;

    manager
        .download_and_register_eps_with_progress(None, {
            let mut current_ep = String::new();
            move |ep_name: &str, percent: f64| {
                if ep_name != current_ep {
                    if !current_ep.is_empty() {
                        println!();
                    }
                    current_ep = ep_name.to_string();
                }
                print!("\r  {ep_name:<30}  {percent:5.1}%");
                io::stdout().flush().ok();
            }
        })
        .await?;
    println!();

    let model = manager.catalog().get_model("qwen2.5-0.5b").await?;
    if !model.is_cached().await? {
        println!("Downloading model...");
        model
            .download(Some(|progress: f64| {
                print!("\r  {progress:.1}%");
                io::stdout().flush().ok();
            }))
            .await?;
        println!();
    }

    model.load().await?;
    let session = ChatSession::new(&model).await?;
    session
        .set_options(RequestOptions {
            search: SearchOptions {
                temperature: Some(0.7),
                max_output_tokens: Some(512),
                ..Default::default()
            },
            ..Default::default()
        })
        .await?;
    println!("Model loaded and ready.");

    let system_prompt = "You are a helpful, friendly assistant. Keep your responses concise and \
                         conversational. If you don't know something, say so.";

    println!("\nChat assistant ready! Type 'quit' to exit.\n");

    let stdin = io::stdin();
    loop {
        print!("You: ");
        io::stdout().flush()?;

        let mut input = String::new();
        stdin.lock().read_line(&mut input)?;
        let input = input.trim();

        if input.eq_ignore_ascii_case("quit") || input.eq_ignore_ascii_case("exit") {
            break;
        }
        if input.is_empty() {
            continue;
        }

        let mut items = Vec::new();
        if session.turn_count() == 0 {
            items.push(Item::system_message(vec![Item::text(system_prompt)]));
        }
        items.push(Item::user_message(vec![Item::text(input)]));

        print!("Assistant: ");
        io::stdout().flush()?;
        let mut stream = session.process_streaming_request(Request::from_items(items));
        while let Some(item) = stream.next().await {
            if let Item::Text {
                text,
                kind: TextKind::Default,
            } = item?
            {
                print!("{text}");
                io::stdout().flush()?;
            }
        }
        println!("\n");
    }

    drop(session);
    model.unload().await?;
    println!("Model unloaded. Goodbye!");

    Ok(())
}

Exécutez l'assistant de chat :

cargo run

Vous voyez un résultat similaire à :

Downloading model: 100.00%
Model loaded and ready.

Chat assistant ready! Type 'quit' to exit.

You: What is photosynthesis?
Assistant: Photosynthesis is the process plants use to convert sunlight, water, and carbon
dioxide into glucose and oxygen. It mainly happens in the leaves, inside structures
called chloroplasts.

You: Why is it important for other living things?
Assistant: It's essential because photosynthesis produces the oxygen that most living things
breathe. It also forms the base of the food chain — animals eat plants or eat other
animals that depend on plants for energy.

You: quit
Model unloaded. Goodbye!

Notez comment l’assistant mémorise le contexte des tours précédents , quand vous demandez « Pourquoi est-il important pour d’autres choses vivantes ? », il sait que vous parlez toujours de photosynthèse.

Référentiel d’exemples

Clonez le dépôt GitHub des exemples Foundry et accédez à l’exemple C++ :

git clone https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/cpp/foundry-local/tutorial-chat-assistant

Installer des packages

Les exemples C++ nécessitent :

  • CMake 3.20 ou version ultérieure.
  • Un compilateur C++20.
  • NuGet CLI sur votre PATH.

Configurez et compilez l’exemple :

cmake -S . -B build
cmake --build build --config Release

Pendant la configuration, l’exemple restaure la version 2.2.1 du Microsoft.AI.Foundry.Local.Runtime package NuGet dans build/_packages. Le package contient les en-têtes C++ et les bibliothèques natives pour Windows, Linux et macOS. Vous n’avez pas besoin d’un package WinML distinct.

La configuration CMake sélectionne les ressources d’exécution de votre système d’exploitation et de votre architecture et copie les bibliothèques natives requises en regard de l’exécutable. Sur macOS et Linux, exécutez l’exécutable à partir de build. Sous Windows, exécutez le fichier .exe depuis build.

Parcourir le catalogue et sélectionner un modèle

Initialisez le Kit de développement logiciel (SDK), sélectionnez un modèle dans le catalogue, puis téléchargez-le et chargez-le :

Configuration config("foundry_local_cpp_tutorial_chat");
Manager manager(std::move(config));
auto model = SelectChatModel(manager.GetCatalog());
if (!model) {
  throw std::runtime_error("No supported CPU chat model was found.");
}
if (!model->IsCached()) {
  model->Download([](float progress) {
    std::cout << "\rDownloading model: " << static_cast<int>(progress) << "%" << std::flush;
    return 0;
  });
  std::cout << "\n";
}
model->Load();

Définir une invite système

Ajoutez une invite système pour mettre en forme la façon dont l’Assistant répond :

Request system_prompt{
    SystemMessage(
        "You are a concise, friendly local assistant. State when you are unsure."),
};
session.ProcessRequest(system_prompt);

Implémenter l'invite multitour

Conservez l’historique des conversations et envoyez-le avec chaque requête :

std::cout << "Enter a message, or type 'exit'.\n";
for (std::string input; std::cout << "You: " && std::getline(std::cin, input);) {
  if (input == "exit" || input == "quit") {
    break;
  }
  if (input.empty()) {
    continue;
  }

  EnableStreaming(session);
  Request request{UserMessage(input)};
  std::cout << "Assistant: ";
  session.ProcessRequest(request);
  std::cout << "\n";
}

Ajouter des réponses en flux

Diffuser le texte de réponse en continu à mesure que le modèle le génère :

void EnableStreaming(ChatSession& session) {
  session.SetStreamingCallback([](Item item) {
    if (item.GetType() == FOUNDRY_LOCAL_ITEM_TEXT &&
        item.GetText().type == FOUNDRY_LOCAL_TEXT_ITEM_TYPE_DEFAULT) {
      std::cout << item.GetText().text << std::flush;
    }
    return 0;
  });
}

Code complet

#include <foundry_local/foundry_local_cpp.h>

#include <iostream>
#include <memory>
#include <string>

using namespace foundry_local;

std::unique_ptr<IModel> SelectChatModel(ICatalog& catalog) {
  for (const std::string alias : {"qwen2.5-0.5b", "qwen3.5-0.8b"}) {
    auto model = catalog.GetModel(alias);
    if (!model) {
      continue;
    }
    for (const auto& variant : model->GetVariants()) {
      const auto info = variant->GetInfo();
      if (info.DeviceType() == FOUNDRY_LOCAL_DEVICE_CPU &&
          (info.Task() == "chat-completion" || info.Task() == "coding")) {
        model->SelectVariant(*variant);
        return model;
      }
    }
  }
  return nullptr;
}

void EnableStreaming(ChatSession& session);

int main() {
  try {
    Configuration config("foundry_local_cpp_tutorial_chat");
    Manager manager(std::move(config));
    auto model = SelectChatModel(manager.GetCatalog());
    if (!model) {
      throw std::runtime_error("No supported CPU chat model was found.");
    }
    if (!model->IsCached()) {
      model->Download([](float progress) {
        std::cout << "\rDownloading model: " << static_cast<int>(progress) << "%" << std::flush;
        return 0;
      });
      std::cout << "\n";
    }
    model->Load();

    {
      ChatSession session(*model);
      session.SetOptions({
          .search = {.temperature = 0.2F, .max_output_tokens = 512, .seed = 42},
      });

      Request system_prompt{
          SystemMessage(
              "You are a concise, friendly local assistant. State when you are unsure."),
      };
      session.ProcessRequest(system_prompt);

      std::cout << "Enter a message, or type 'exit'.\n";
      for (std::string input; std::cout << "You: " && std::getline(std::cin, input);) {
        if (input == "exit" || input == "quit") {
          break;
        }
        if (input.empty()) {
          continue;
        }

        EnableStreaming(session);
        Request request{UserMessage(input)};
        std::cout << "Assistant: ";
        session.ProcessRequest(request);
        std::cout << "\n";
      }
    }

    model->Unload();
    manager.Shutdown();
  } catch (const Error& error) {
    std::cerr << "Foundry Local error [" << error.Code() << "]: " << error.what() << "\n";
    return 1;
  } catch (const std::exception& error) {
    std::cerr << "Error: " << error.what() << "\n";
    return 1;
  }

  return 0;
}

void EnableStreaming(ChatSession& session) {
  session.SetStreamingCallback([](Item item) {
    if (item.GetType() == FOUNDRY_LOCAL_ITEM_TEXT &&
        item.GetText().type == FOUNDRY_LOCAL_TEXT_ITEM_TYPE_DEFAULT) {
      std::cout << item.GetText().text << std::flush;
    }
    return 0;
  });
}

Exécutez l'assistant de chat :

./build/tutorial-chat-assistant

Nettoyer les ressources

Les poids du modèle restent dans votre cache local après avoir déchargé un modèle. Cela signifie que la prochaine fois que vous exécutez l’application, l’étape de téléchargement est ignorée et le modèle se charge plus rapidement. Aucun nettoyage supplémentaire n’est nécessaire, sauf si vous souhaitez récupérer de l’espace disque.