Esercitazione: Creare un'applicazione RAG

Creare un'applicazione di generazione aumentata di recupero (RAG) che risponde a domande su una raccolta di documenti interamente nel dispositivo. Rag combina la ricerca basata sull'incorporamento con un modello di chat in modo che le risposte siano basate sui propri dati anziché basarsi esclusivamente sulle conoscenze di training del modello.

In questa esercitazione si apprenderà come:

• Configurare un progetto e installare Foundry Local SDK
• Creare una knowledge base di documenti di testo
• Generare incorporamenti per i documenti
• Cercare documenti pertinenti in base alla somiglianza
• Generare risposte basate sul contesto recuperato
• Pulire le risorse

Prerequisiti

• Un computer Windows, macOS o Linux con almeno 8 GB di RAM.
• Python 3.11 o versione successiva installata.

Installare i pacchetti

Se si sviluppa o si esegue la spedizione in Windows, selezionare la scheda Windows. Il pacchetto Windows si integra con il runtime Windows ML, che fornisce la stessa area di attacco API con un'ampiezza più ampia di accelerazione hardware.

Windows

pip install foundry-local-sdk-winml openai

Multipiattaforma

pip install foundry-local-sdk openai

Creare una base di conoscenza

Un'applicazione RAG richiede una raccolta di documenti da cercare. Definire un elenco di stringhe di testo che fungono da knowledge base. In un'applicazione di produzione, l'elenco può essere un paragrafo di file, record di database o qualsiasi altra origine di testo.

Creare un file denominato main.py e aggiungere il codice seguente:

import math
from foundry_local_sdk import Configuration, FoundryLocalManager

# Knowledge base — each string represents a document
documents = [
    "Foundry Local runs AI models directly on your device without cloud connectivity.",
    "The Foundry Local SDK supports Python, C#, JavaScript, and Rust.",
    "Embedding models convert text into numerical vectors for similarity search.",
    "Foundry Local uses ONNX Runtime for efficient model inference on CPUs and GPUs.",
    "The model catalog provides pre-optimized models that you can download and run locally.",
    "Retrieval-augmented generation grounds model responses in your own data.",
    "Vector similarity search finds documents that are semantically close to a query.",
    "Chat completions generate natural language responses from a prompt and context.",
]

Generare incorporamenti di documenti

Inizializzare l'SDK, caricare un modello di incorporamento e convertire ogni documento in un vettore numerico. Questi vettori rappresentano il significato semantico di ogni documento e consentono la ricerca di somiglianza.

Aggiungere il codice seguente a main.py:

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

    # Load the embedding model
    embedding_model = manager.catalog.get_model("qwen3-embedding-0.6b")
    embedding_model.download(
        lambda p: print(f"\rDownloading embedding model: {p:.1f}%", end="", flush=True)
    )
    print()
    embedding_model.load()
    embedding_client = embedding_model.get_embedding_client()

    # Embed all documents in a single batch call
    response = embedding_client.generate_embeddings(documents)
    doc_embeddings = [item.embedding for item in response.data]
    print(f"Indexed {len(doc_embeddings)} documents.")

Il generate_embeddings metodo accetta un elenco di stringhe e restituisce un vettore per input. Ogni vettore acquisisce il significato semantico del testo, quindi documenti simili producono vettori vicini nello spazio di incorporamento.

Cercare documenti pertinenti

Per trovare documenti correlati a una query, confrontare l'incorporamento della query con ogni incorporamento di documenti utilizzando la similarità coseno. La somiglianza del coseno misura la vicinanza di due vettori nella direzione, indipendentemente dalla grandezza. I valori vicini a 1,0 indicano una somiglianza elevata.

Aggiungere le funzioni helper seguenti sopra main() in main.py:

def cosine_similarity(a, b):
    """Compute cosine similarity between two vectors."""
    dot = sum(x * y for x, y in zip(a, b))
    norm_a = math.sqrt(sum(x * x for x in a))
    norm_b = math.sqrt(sum(x * x for x in b))
    return dot / (norm_a * norm_b) if norm_a and norm_b else 0.0


def find_relevant(query_embedding, doc_embeddings, top_k=2):
    """Return the indices and scores of the top-k most similar documents."""
    scores = []
    for i, doc_emb in enumerate(doc_embeddings):
        score = cosine_similarity(query_embedding, doc_emb)
        scores.append((i, score))
    scores.sort(key=lambda x: x[1], reverse=True)
    return scores[:top_k]

La find_relevant funzione classifica tutti i documenti in base alla somiglianza e restituisce le corrispondenze principali. Questo approccio funziona bene per le raccolte di piccole dimensioni. Per set di dati di dimensioni maggiori, prendere in considerazione un database vettoriale dedicato.

Generare risposte fondate

Caricare un modello di chat e combinare i documenti recuperati con la domanda dell'utente in una richiesta di sistema. Il modello di chat usa il contesto fornito per generare una risposta basata sui tuoi documenti.

Aggiungere il codice seguente alla main() funzione dopo la sezione incorporamento:

    # Load the chat model
    chat_model = manager.catalog.get_model("qwen2.5-0.5b")
    chat_model.download(
        lambda p: print(f"\rDownloading chat model: {p:.1f}%", end="", flush=True)
    )
    print()
    chat_model.load()
    chat_client = chat_model.get_chat_client()

    print("\nModels loaded. Ready for questions.")
    print("\nThe knowledge base contains information about:")
    print("  - Foundry Local features and architecture")
    print("  - Supported programming languages")
    print("  - Embedding models and vector search")
    print("  - ONNX Runtime inference")
    print("  - The model catalog")
    print("  - RAG and chat completions")
    print("\nExample questions:")
    print('  "What programming languages does the SDK support?"')
    print('  "How does Foundry Local run models?"')
    print('  "What is retrieval-augmented generation?"')
    print('\nType "quit" to exit.\n')

    # Interactive query loop
    while True:
        query = input("Question: ").strip()
        if not query or query.lower() == "quit":
            break

        # Embed the query
        query_response = embedding_client.generate_embedding(query)
        query_embedding = query_response.data[0].embedding

        # Retrieve the most relevant documents
        results = find_relevant(query_embedding, doc_embeddings, top_k=2)
        context = "\n".join(f"- {documents[i]}" for i, _ in results)

        # Build the prompt with retrieved context
        messages = [
            {
                "role": "system",
                "content": (
                    "Answer the user's question using only the provided context. "
                    "If the context doesn't contain enough information, say so.\n\n"
                    f"Context:\n{context}"
                ),
            },
            {"role": "user", "content": query},
        ]

        # Stream the response
        print("Answer: ", end="", flush=True)
        for chunk in chat_client.complete_streaming_chat(messages):
            content = chunk.choices[0].delta.content
            if content:
                print(content, end="", flush=True)
        print("\n")

    # Clean up
    embedding_model.unload()
    chat_model.unload()
    print("Models unloaded. Done!")


if __name__ == "__main__":
    main()

Il prompt di sistema indica al modello di rispondere usando solo il contesto recuperato. La richiesta di sistema mantiene le risposte contenute nei documenti e riduce le risposte non corrette. L'output di streaming stampa ogni token man mano che viene generato, rendendo la risposta interattiva.

Codice completo

Ecco l'applicazione completa che combina tutti i passaggi:

import math
from foundry_local_sdk import Configuration, FoundryLocalManager

# Knowledge base
documents = [
    "Foundry Local runs AI models directly on your device without cloud connectivity.",
    "The Foundry Local SDK supports Python, C#, JavaScript, and Rust.",
    "Embedding models convert text into numerical vectors for similarity search.",
    "Foundry Local uses ONNX Runtime for efficient model inference on CPUs and GPUs.",
    "The model catalog provides pre-optimized models that you can download and run locally.",
    "Retrieval-augmented generation grounds model responses in your own data.",
    "Vector similarity search finds documents that are semantically close to a query.",
    "Chat completions generate natural language responses from a prompt and context.",
]


def cosine_similarity(a, b):
    """Compute cosine similarity between two vectors."""
    dot = sum(x * y for x, y in zip(a, b))
    norm_a = math.sqrt(sum(x * x for x in a))
    norm_b = math.sqrt(sum(x * x for x in b))
    return dot / (norm_a * norm_b) if norm_a and norm_b else 0.0


def find_relevant(query_embedding, doc_embeddings, top_k=2):
    """Return the indices and scores of the top-k most similar documents."""
    scores = []
    for i, doc_emb in enumerate(doc_embeddings):
        score = cosine_similarity(query_embedding, doc_emb)
        scores.append((i, score))
    scores.sort(key=lambda x: x[1], reverse=True)
    return scores[:top_k]


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

    # Load the embedding model
    embedding_model = manager.catalog.get_model("qwen3-embedding-0.6b")
    embedding_model.download(
        lambda p: print(f"\rDownloading embedding model: {p:.1f}%", end="", flush=True)
    )
    print()
    embedding_model.load()
    embedding_client = embedding_model.get_embedding_client()

    # Embed all documents
    response = embedding_client.generate_embeddings(documents)
    doc_embeddings = [item.embedding for item in response.data]
    print(f"Indexed {len(doc_embeddings)} documents.")

    # Load the chat model
    chat_model = manager.catalog.get_model("qwen2.5-0.5b")
    chat_model.download(
        lambda p: print(f"\rDownloading chat model: {p:.1f}%", end="", flush=True)
    )
    print()
    chat_model.load()
    chat_client = chat_model.get_chat_client()

    print("\nModels loaded. Ready for questions.")
    print("\nThe knowledge base contains information about:")
    print("  - Foundry Local features and architecture")
    print("  - Supported programming languages")
    print("  - Embedding models and vector search")
    print("  - ONNX Runtime inference")
    print("  - The model catalog")
    print("  - RAG and chat completions")
    print("\nExample questions:")
    print('  "What programming languages does the SDK support?"')
    print('  "How does Foundry Local run models?"')
    print('  "What is retrieval-augmented generation?"')
    print('\nType "quit" to exit.\n')

    # Interactive query loop
    while True:
        query = input("Question: ").strip()
        if not query or query.lower() == "quit":
            break

        # Embed the query
        query_response = embedding_client.generate_embedding(query)
        query_embedding = query_response.data[0].embedding

        # Retrieve the most relevant documents
        results = find_relevant(query_embedding, doc_embeddings, top_k=2)
        context = "\n".join(f"- {documents[i]}" for i, _ in results)

        # Build the prompt with retrieved context
        messages = [
            {
                "role": "system",
                "content": (
                    "Answer the user's question using only the provided context. "
                    "If the context doesn't contain enough information, say so.\n\n"
                    f"Context:\n{context}"
                ),
            },
            {"role": "user", "content": query},
        ]

        # Stream the response
        print("Answer: ", end="", flush=True)
        for chunk in chat_client.complete_streaming_chat(messages):
            content = chunk.choices[0].delta.content
            if content:
                print(content, end="", flush=True)
        print("\n")

    # Clean up
    embedding_model.unload()
    chat_model.unload()
    print("Models unloaded. Done!")


if __name__ == "__main__":
    main()

Eseguire l'applicazione:

python main.py

Viene visualizzato un output simile al seguente:

Downloading embedding model: 100.0%
Indexed 8 documents.
Downloading chat model: 100.0%

Models loaded. Ready for questions.

The knowledge base contains information about:
  - Foundry Local features and architecture
  - Supported programming languages
  - Embedding models and vector search
  - ONNX Runtime inference
  - The model catalog
  - RAG and chat completions

Example questions:
  "What programming languages does the SDK support?"
  "How does Foundry Local run models?"
  "What is retrieval-augmented generation?"

Type "quit" to exit.

Question: What programming languages does the SDK support?
Answer: The Foundry Local SDK supports Python, C#, JavaScript, and Rust.

Question: quit
Models unloaded. Done!

Pulire le risorse

I pesi del modello rimangono nella cache locale dopo lo scaricamento di un modello. Al successivo esecuzione dell'applicazione, il passaggio di download viene ignorato e i modelli vengono caricati più velocemente. Non è necessaria alcuna pulizia aggiuntiva, a meno che non si voglia recuperare spazio su disco.

Contenuto correlato

• Generare incorporamenti di testo con Foundry Local
• Esercitazione: Creare un assistente chat a più turni
• Usare l'API di completamento della chat nativa con Foundry Local
• Informazioni di riferimento su Foundry Local SDK