Nota

Crea un agente AI con il server del protocollo di comunicazione multi-agente per la risoluzione delle fatture

Introduzione

Le aziende che si occupano di un grande volume di prodotti - come distributori, industrie e catene di vendita al dettaglio - spesso affrontano la sfida di identificare i prodotti in base a descrizioni testuali imprecise, incomplete o varie. In ambienti in cui i dati vengono immessi manualmente, errori di battitura, abbreviazioni e nomi commerciali diversi possono rendere difficile identificare correttamente gli articoli in sistemi come Enterprise Resource Planning (ERP), Customer Relationship Management (CRM) e piattaforme di e-commerce.

In questo scenario, c'è una necessità comune di strumenti che possono:

In questa esercitazione verrà descritto come creare un agente AI specializzato nella risoluzione delle incoerenze nelle fatture di reso dei clienti. L'agente è in grado di interagire con un server MCP che fornisce strumenti di ricerca vettoriale e recupero fatture, consentendo all'agente di trovare automaticamente la fattura AR originale della società in base alle informazioni fornite dal cliente.

Un server MCP (Model Context Protocol) è un componente software responsabile della mediazione della comunicazione tra agenti intelligenti e servizi esterni attraverso un protocollo standardizzato di messaggi e strumenti. Funge da ponte tra i modelli linguistici (LLM) e le API esistenti, consentendo agli agenti AI di accedere a funzionalità specifiche dei sistemi legacy senza la necessità di riscriverli o adattarli direttamente.

Come funziona

Server MCP:

Utilizzo di applicazioni legacy

Le applicazioni legacy spesso forniscono già funzionalità tramite database, file o API interne. Con un server MCP è possibile:

Vantaggi

Questo agente si basa su un modello di linguaggio AI generativa di Oracle Cloud Infrastructure (OCI) e si integra con strumenti dichiarati dinamicamente gestiti da un server MCP.

Con l'integrazione di questi due componenti, il sistema abilita un agente basato su Oracle LLM:

Questo design modulare consente la riutilizzabilità e la facile evoluzione del sistema in domini diversi dalle fatture.

Obiettivi

Prerequisiti

Installare requirements.txt con:

installazione pipeline -r requirements.txt

Task 1: Creare un Oracle Database 23ai (sempre gratuito)

In questo task verrà descritto come eseguire il provisioning di un Oracle Database 23ai in modalità Sempre gratuita. Questa versione offre un ambiente completamente gestito, ideale per lo sviluppo, il test e l'apprendimento, senza costi aggiuntivi.

  1. Eseguire il login a OCI Console, andare a Oracle Database, Autonomous Database e fare clic su Crea istanza di Autonomous Database.

  2. Immettere le informazioni riportate di seguito.

    • Nome database: immettere un nome identificativo per l'istanza.
    • Tipo di carico di lavoro: selezionare Data Warehouse o Elaborazione transazioni in base alle proprie esigenze.
    • Compartimento: selezionare un compartimento appropriato per organizzare le risorse.

  3. Selezionare Sempre gratis per assicurarsi che il provisioning dell'istanza venga eseguito gratuitamente.

  4. Creare una password sicura per l'utente ADMIN, che verrà utilizzata per accedere al database.

  5. Rivedere le impostazioni e fare clic su Crea Autonomous Database. Attendere alcuni minuti prima che il provisioning dell'istanza venga eseguito e sia disponibile per l'uso.

Task 2: eseguire lo script di creazione della tabella Autonomous Database

Preparare il database per il nostro caso d'uso. Scaricare ed eseguire lo script SQL da qui: script.sql che crea tre tabelle essenziali (PRODUCTS, INVOICE e ITEM_INVOICE) per lo scenario di riconciliazione delle fatture con gli agenti AI.

  1. Andare a OCI Console, andare a Oracle Database, Autonomous Database e fare clic sul nome dell'istanza appena creata.

  2. Fare clic su Azioni database e su SQL per aprire la console SQL nel browser.

  3. Scaricare e aprire il file script.sql localmente e incollare tutti i contenuti nell'editor della console SQL.

  4. Fare clic su Esegui o premere Ctrl + Invio. Attendere la conferma che l'esecuzione dei comandi è riuscita.

  5. Eseguire i comandi seguenti per verificare che le tabelle siano state create.

    SELECT table_name FROM user_tables;

Task 3: Inserimento di dati di esempio nelle tabelle

Inserire dati fittizi che simuleranno uno scenario reale per l'applicazione degli agenti AI. Useremo due script SQL:

Questi dati verranno utilizzati dagli agenti AI per risolvere le incoerenze nelle fatture di reso.

  1. Andare a OCI Console, andare a Oracle Database, Autonomous Database e fare clic sul nome dell'istanza appena creata.

  2. Fare clic su Azioni database e su SQL per aprire la console SQL nel browser.

  3. Scaricare e aprire il contenuto del file insert_products_books.sql e incollarlo nell'editor SQL.

  4. Fare clic su Esegui o premere Ctrl + Invio.

  5. A questo punto, scaricare e aprire il contenuto del file invoice_data_insert.sql e incollarlo nell'editor.

  6. Fare clic su Esegui o premere Ctrl + Invio.

  7. Eseguire il comando seguente per controllare i dati.

    SELECT * FROM PRODUCTS;
SELECT * FROM INVOICE;
SELECT * FROM ITEM_INVOICE;

Task 4: Creazione e compilazione della funzione di ricerca avanzata nel database

Creare una funzione PL/SQL denominata fn_advanced_search, che esegue ricerche intelligenti per le parole chiave nelle descrizioni dei prodotti. Questa funzione verrà utilizzata dagli agenti AI come parte dello strumento resolve_ean, consentendo loro di trovare il codice EAN più vicino in base alla descrizione fornita da un cliente sulla nota di reso.

Cosa fa la funzione?

Seguire i passi indicati:

  1. Copiare e incollare lo script similarity_search.sql completo nella console SQL di Autonomous Database.

    Tra queste sono incluse le seguenti:

    • Creazione della tabella products (se non è già stata eseguita).
    • Creazione di un indice di testo.
    • Tipi product_result e product_result_tab.
    • Funzione fn_advanced_search.
    • Test opzionali.

  2. Eseguire lo script completo. Il risultato deve essere Function created e Type created.

  3. Eseguire la seguente query per testare la funzione con descrizioni simulate.

    SELECT *
FROM TABLE(fn_advanced_search('harry poter askaban'))
ORDER BY similarity DESC;

Task 5: Vectorizzare i prodotti per la ricerca semantica con l'intelligenza artificiale

In questo compito, completeremo la ricerca avanzata basata su SQL con un nuovo approccio basato su vettori semantici. Ciò sarà particolarmente utile per gli agenti AI che utilizzano incorporamenti (rappresentazioni numeriche di frasi) per confrontare la somiglianza tra le descrizioni dei prodotti - in modo più flessibile e intelligente rispetto alle ricerche di parole o fonetiche.

Per fare ciò, utilizzeremo lo script Python (process_vector_products.py), che si connette al database Oracle, estrae i prodotti dalla tabella PRODUCTS, trasforma le loro descrizioni in vettori (embeddings) e crea un indice vettoriale utilizzando il database Oracle stesso.

Cosa fa lo script?

Nota: gli incorporamenti vengono convertiti in byte con np.float32.tobytes() da memorizzare come BLOB. Per recuperare i vettori, utilizzare np.frombuffer(blob, dtype=np.float32).

Questo formato consente di eseguire ricerche future di somiglianza direttamente utilizzando SQL o caricando i vettori dal database per le operazioni con np.dot, cosine_similarity o l'integrazione con LLM.

Questo script genera integrazioni semantiche per i prodotti e scrive questi vettori nel database Oracle 23ai. I punti principali sono evidenziati di seguito:

Esecuzione dello script:

Tenere presente che è necessario scaricare e configurare Oracle Wallet. Eseguire nel terminale.

python process_vector_products.py

Fatto. I prodotti nel database sono stati vettorializzati.

Perché è importante?

La ricerca vettoriale è molto efficace per trovare prodotti anche quando la descrizione è soggettiva, imprecisa o in linguaggio naturale.

Comprendere il codice: agente LLM con server MCP

Questo progetto è composto da 3 componenti principali:

Comprendi le funzionalità di ogni componente e evidenzia in dettaglio le parti più importanti del codice.

Task 6: Configurazione del modello e degli incorporamenti nell'agente MCP

Configura il modello di linguaggio e le integrazioni utilizzate dall'agente conversazionale in base al protocollo MCP, utilizzando i servizi OCI Generative AI.

  1. Configurare il modello di lingua (LLM, Language Model).

    Il modello linguistico è responsabile dell'interpretazione dei messaggi, della generazione di risposte e dell'azione come cervello principale dell'agente.

    • Eseguire la configurazione nel file main.py.

      from langchain_community.chat_models.oci_generative_ai import ChatOCIGenAI

llm = ChatOCIGenAI(
    model_id="cohere.command-r-08-2024",
    service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
    compartment_id="ocid1.compartment.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    auth_profile="DEFAULT",
    model_kwargs={"temperature": 0.1, "top_p": 0.75, "max_tokens": 2000}
)
      Parametro Descrizione
      model_id ID modello AI generativa, ad esempio cohere.command-r-08-2024
      service_endpoint Endpoint regionale del servizio AI generativa
      compartment_id OCID del compartimento OCI
      auth_profile Nome del profilo configurato nel file ~/.oci/config
      model_kwargs Temperatura, top-p e risposta

    • Elenca i modelli disponibili.

      • Uso dell'interfaccia CLI OCI:

        oci generative-ai model list --compartment-id <seu_compartment_id>

      • Utilizzando l'SDK Python:

        from oci.generative_ai import GenerativeAiClient
from oci.config import from_file

config = from_file(profile_name="DEFAULT")
client = GenerativeAiClient(config)

models = client.list_models(compartment_id=config["compartment_id"])
for model in models.data:
    print(model.display_name, model.model_id)

  2. Configura le integrazioni per la ricerca semantica.

    La ricerca di prodotti simili o informazioni contestuali dipende dalle integrazioni vettoriali.

    Esempio di utilizzo nell'agente:

    @mcp.tool()
def search_vectorized_product(description: str) -> dict:
    """
        Searches for a product by description using embeddings.
    """
    return sercher.search_similar_products(description)

    Modificare i parametri (product_search.py) come indicato di seguito:

    
class SimilarProductSearch:
    def __init__(
            self,
            top_k=5,
            minimum_distance=1.0,
            model_id="cohere.embed-english-light-v3.0",
            service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
            compartment_id="ocid1.compartment.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
            auth_profile="DEFAULT",
            wallet_path="/WALLET_PATH/Wallet_oradb23ai",
            db_alias="oradb23ai_high",
            username="USER",
            password="Password"
    ):
    Parametro Descrizione
    top_k Numero di consigli restituiti.
    minimum_distance Distanza massima per considerare il risultato rilevante.
    model_id ID del modello di incorporamento in OCI (ad esempio, cohere.embed-english-light-v3.0).
    service_endpoint Endpoint regionale dell'AI generativa OCI.
    compartment_id OCID compartimenti.
    auth_profile Nome del profilo nel file ~/.oci/config.
    wallet_path Percorso del wallet di Oracle Database 23ai.
    db_alias Alias del database.
    username Utente database.
    password Password del database.

    Configurare il server MCP:

    Proprio come hai fatto quando esegui il codice process_vector_products.py, dovrai configurare Oracle Wallet per il database Oracle Database 23ai.

    Modificare i parametri in base alle impostazioni:

    import os

# Oracle Wallet settings
WALLET_PATH = "/path/to/Wallet"
DB_ALIAS = "oradb23ai_high"
USERNAME = "admin"
PASSWORD = "..."

# Define the environment variable required for the Oracle client
os.environ["TNS_ADMIN"] = WALLET_PATH

    E poi eseguire process_vector_products.py per vettorializzare i prodotti in Oracle Database 23ai.

    python process_vector_products.py

Con questo, il modello LLM e le integrazioni sono pronti per essere utilizzati dall'agente MCP con LangGraph e LangChain.

  1. Eseguire il file main.py utilizzando il comando seguente.

    python main.py

  2. Quando viene visualizzato il prompt Voi:, immettere l'istruzione seguente.

    { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "SP"}

    Nota: il nome del libro Harry Potter e Azkaban è scritto in modo errato, ma il motore può trovarlo senza problemi.

    img.png

    img_1.png

    Tenere presente che i servizi sono stati eseguiti:

    fetch_vectorized_product
resolve_ean
search_invoices_by_criteria

  3. Inserire ora l'istruzione seguente.

    { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26}

    Non è stato trovato alcun record fattura. L'ubicazione è la chiave per trovare una fattura.

    img_2.png

  4. Inserire ora l'istruzione seguente.

    { "customer": "Customer 108",  "description": "Harry Poter", "location": "SP"}

    Questa volta, immettiamo l'ubicazione, ma omettiamo il prezzo unitario.

    img_3.png

    La fattura è stata trovata. Questo perché il prezzo non è fondamentale, ma aiuta a colmare il divario per essere più assertivo.

    Di seguito sono riportati alcuni esempi di test.

     { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "SP"}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "location": "SP"}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "RJ"}

 { "customer": "Customer 125",  "description": "Harry Potter Chamber", "price": 79.16, "location": "SP"}

 { "customer": "Customer 125",  "description": "Harry Potter Chamber", "price": 79.15, "location": "SP"}

Task 8: Visualizza l'osservabilità con Phoenix

Immettere http://localhost:6006/ nel browser per visualizzare l'osservabilità con Phoenix.

img.png

img.png

img.png

Conferme

Altre risorse di apprendimento

Esplora altri laboratori su docs.oracle.com/learn o accedi a più contenuti di formazione gratuiti sul canale YouTube di Oracle Learning. Inoltre, visitare education.oracle.com/learning-explorer per diventare Oracle Learning Explorer.

Per la documentazione del prodotto, visitare Oracle Help Center.