Integrare con LangChain

Utilizza Model Armor con LangChain per migliorare la sicurezza delle tue applicazioni AI analizzando in modo proattivo i prompt e le risposte degli LLM. Per contribuire a prevenire input dannosi, verificare la sicurezza dei contenuti e applicare le norme di sicurezza in modo coerente nelle tue applicazioni di AI, aggiungi Model Armor ai tuoi flussi di lavoro LangChain.

Prima di iniziare

Prima di implementare il codice, completa i seguenti Google Cloud passaggi di configurazione:

  • Seleziona o crea un progetto e abilita la fatturazione.
  • Abilita l'API Model Armor nel tuo progetto.
  • Configura l'autenticazione utilizzando gcloud o impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.
  • Assicurati che il account di servizio disponga del ruolo Utente Model Armor (roles/modelarmor.user). Per gestire i modelli, devi disporre del ruolo Model Armor Admin(roles/modelarmor.admin).
  • Crea modelli nella console Google Cloud .

Eseguibili

Per utilizzare Model Armor con LangChain, hai bisogno di due runnables principali che si adattino all'interfaccia LangChain standard.

  • ModelArmorSanitizePromptRunnable: questo componente esamina l'input utente (prompt) prima che raggiunga l'LLM. Rileva input dannosi o violazioni delle norme.

  • ModelArmorSanitizeResponseRunnable: questo componente esamina l'output generato dal LLM prima di restituirlo all'utente. Eventuali modifiche che l'utente apporta alla risposta dopo il controllo di sicurezza principale non vengono filtrate e ti verranno inviate nel loro stato grezzo.

Installa i pacchetti Python richiesti

Installa i seguenti pacchetti Python:

  • langchain-google-community versione 3.0.4 o successive
  • langchain-google-genai
pip install langchain-google-community langchain-google-genai

Pattern di utilizzo

Puoi utilizzare Model Armor con LangChain tramite il concatenamento di base o utilizzando il middleware.

Concatenazione di base

Il modo più comune per utilizzare Model Armor è concatenare il sanificatore di prompt, il modello e il sanificatore di risposte utilizzando l'operatore pipe del linguaggio di espressione LangChain (LCEL).

from langchain_google_community.model_armor import (
    ModelArmorSanitizePromptRunnable,
    ModelArmorSanitizeResponseRunnable,
)
from langchain_google_genai import ChatGoogleGenerativeAI

# Initialize Model Armor runnables
sanitize_prompt = ModelArmorSanitizePromptRunnable(
    project="PROJECT_ID",
    location="LOCATION",
    template_id="TEMPLATE_ID",
    fail_open="SANITIZE_PROMPT_ERROR_HANDLING"
)

sanitize_response = ModelArmorSanitizeResponseRunnable(
    project="PROJECT_ID",
    location="LOCATION",
    template_id="TEMPLATE_ID",
    fail_open="SANITIZE_RESPONSE_ERROR_HANDLING"
)

# Initialize the model
llm = ChatGoogleGenerativeAI(model="gemini-2.5-flash", <var>...</var>)

# Build the chain
chain = sanitize_prompt | llm | sanitize_response

# Invoke
try:
    result = chain.invoke("<var>YOUR_USER_PROMPT_HERE</var>")
    print(result)
except ValueError as e:
    print(f"Content blocked: {e}")

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: la posizione del template.
  • TEMPLATE_ID: l'ID del modello Model Armor creato in Prima di iniziare.
  • SANITIZE_PROMPT_ERROR_HANDLING: un valore booleano che controlla la gestione degli errori per ModelArmorSanitizePromptRunnable, True o False.

  • SANITIZE_RESPONSE_ERROR_HANDLING: un valore booleano che controlla la gestione degli errori per ModelArmorSanitizeResponseRunnable, True o False.

    Quando gestisce gli errori, Model Armor si comporta nel seguente modo:

    • True: registra un avviso, ma consente il passaggio dei contenuti anche se vengono rilevati rischi.
    • False: genera un ValueError e blocca l'esecuzione quando vengono rilevati contenuti non sicuri.

Middleware per gli agenti

Per gli agenti LangChain che utilizzano strumenti, puoi utilizzare ModelArmorMiddleware. Questo middleware applica l'eseguibile di sanificazione pertinente in diversi punti di interazione che l'agente LangChain attraversa quando utilizza gli strumenti.

from langchain.agents import create_agent
from langchain.tools import tool
from langchain_google_genai import ChatGoogleGenerativeAI

from langchain_google_community.model_armor import (
    ModelArmorMiddleware,
    ModelArmorSanitizePromptRunnable,
    ModelArmorSanitizeResponseRunnable,
)

# Create Model Armor sanitizers (same configuration as earlier sections)
prompt_sanitizer = ModelArmorSanitizePromptRunnable(
    project="PROJECT_ID",
    location="LOCATION",
    template_id="TEMPLATE_ID",
    fail_open="SANITIZE_PROMPT_ERROR_HANDLING",
)

response_sanitizer = ModelArmorSanitizeResponseRunnable(
    project="PROJECT_ID",
    location="LOCATION",
    template_id="TEMPLATE_ID",
    fail_open="SANITIZE_RESPONSE_ERROR_HANDLING",
)

# Wrap them in the official Model Armor middleware
model_armor_middleware = ModelArmorMiddleware(
    prompt_sanitizer=prompt_sanitizer,
    response_sanitizer=response_sanitizer,
)

# --- Create agent with Model Armor middleware ---
agent = create_agent(
    model="SOME_GEMINI_VERSION",
    tools=[],
    middleware=[model_armor_middleware],
)

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: la posizione del template.
  • TEMPLATE_ID: l'ID del modello Model Armor creato in Prima di iniziare.
  • SANITIZE_PROMPT_ERROR_HANDLING: un valore booleano che controlla la gestione degli errori per ModelArmorSanitizePromptRunnable, True o False.

  • SANITIZE_RESPONSE_ERROR_HANDLING: un valore booleano che controlla la gestione degli errori per ModelArmorSanitizeResponseRunnable, True o False.

    Quando gestisce gli errori, Model Armor si comporta nel seguente modo:

    • True: registra un avviso, ma consente il passaggio dei contenuti anche se vengono rilevati rischi.
    • False: genera un ValueError e blocca l'esecuzione quando vengono rilevati contenuti non sicuri.

Questa configurazione garantisce che anche quando l'agente esegue ragionamenti multi-step o utilizza strumenti, gli input e gli output vengano esaminati.

Controllo dei documenti

Puoi utilizzare i runnable di Model Armor per controllare i documenti caricati prima di elaborarli. Questo è essenziale per i workflow come il riepilogo, in cui il documento di origine potrebbe contenere contenuti dannosi nascosti. Puoi caricare il contenuto del file e passarlo attraverso ModelArmorSanitizePromptRunnable prima di inviarlo all'LLM.

Gestione degli eventi personalizzati

Per l'osservabilità, i runnable inviano un evento on_model_armor_finding quando vengono rilevati contenuti non sicuri. Puoi collegare un gestore callback personalizzato per registrare dettagli specifici (come risultati e contenuti) o attivare avvisi senza interrompere il flusso dell'applicazione.

from langchain_core.callbacks import BaseCallbackHandler

class SecurityHandler(BaseCallbackHandler):
    def on_custom_event(self, name, data, **kwargs):
        if name == "on_model_armor_finding":
            print(f"Alert: {data['findings']} detected in {data['template_id']}")

# Attach to config
chain.invoke(user_input, config={"callbacks": [SecurityHandler()]})