Mengintegrasikan dengan LangChain

Gunakan Model Armor dengan LangChain untuk meningkatkan keamanan aplikasi AI Anda dengan secara proaktif menyaring perintah dan respons LLM. Untuk membantu mencegah input berbahaya, verifikasi keamanan konten, dan terapkan kebijakan keamanan secara konsisten di seluruh aplikasi AI Anda, tambahkan Model Armor ke alur kerja LangChain Anda.

Sebelum memulai

Sebelum menerapkan kode, selesaikan langkah-langkah penyiapan Google Cloud berikut:

  • Pilih atau buat project dan aktifkan penagihan.
  • Aktifkan Model Armor API di project Anda.
  • Siapkan autentikasi menggunakan gcloud atau dengan menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS.
  • Pastikan akun layanan Anda memiliki peran Pengguna Model Armor (roles/modelarmor.user). Untuk mengelola template, Anda memerlukan peran Admin Model Armor(roles/modelarmor.admin)
  • Buat template di konsol Google Cloud .

Dapat dijalankan

Untuk menggunakan Model Armor dengan LangChain, Anda memerlukan dua runnable utama yang sesuai dengan antarmuka LangChain standar.

  • ModelArmorSanitizePromptRunnable: Komponen ini menyaring input pengguna (perintah) sebelum mencapai LLM. Deteksi input berbahaya atau pelanggaran kebijakan.

  • ModelArmorSanitizeResponseRunnable: Komponen ini menyaring output yang dihasilkan oleh LLM sebelum ditampilkan kepada pengguna. Setiap modifikasi yang dilakukan pengguna pada respons setelah pemeriksaan keamanan utama tidak difilter dan akan sampai kepada Anda dalam keadaan mentah.

Instal paket Python yang diperlukan

Instal paket Python berikut:

  • langchain-google-community versi 3.0.4 atau yang lebih baru
  • langchain-google-genai
pip install langchain-google-community langchain-google-genai

Pola penggunaan

Anda dapat menggunakan Model Armor dengan LangChain baik dengan penggabungan dasar atau menggunakan middleware.

Perantaian dasar

Cara paling umum untuk menggunakan Model Armor adalah dengan menggabungkan sanitizer perintah, model, dan sanitizer respons menggunakan operator pipe LangChain Expression Language (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}")

Ganti kode berikut:

  • PROJECT_ID: Google Cloud Project ID Anda.
  • LOCATION: lokasi template.
  • TEMPLATE_ID: ID template Model Armor yang dibuat di Sebelum memulai.
  • SANITIZE_PROMPT_ERROR_HANDLING: boolean yang mengontrol penanganan error untuk ModelArmorSanitizePromptRunnable; True atau False.

  • SANITIZE_RESPONSE_ERROR_HANDLING: boolean yang mengontrol penanganan error untuk ModelArmorSanitizeResponseRunnable; True atau False.

    Saat menangani error, Model Armor berperilaku sebagai berikut:

    • True: mencatat peringatan, tetapi mengizinkan konten lolos meskipun risiko terdeteksi.
    • False: memunculkan ValueError dan memblokir eksekusi saat konten tidak aman terdeteksi.

Middleware untuk agen

Untuk agen LangChain yang menggunakan alat, Anda dapat menggunakan ModelArmorMiddleware. Middleware ini menerapkan runnable sanitizer yang relevan pada berbagai titik interaksi yang dilalui agen LangChain saat menggunakan alat.

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],
)

Ganti kode berikut:

  • PROJECT_ID: Google Cloud Project ID Anda.
  • LOCATION: lokasi template.
  • TEMPLATE_ID: ID template Model Armor yang dibuat di Sebelum memulai.
  • SANITIZE_PROMPT_ERROR_HANDLING: boolean yang mengontrol penanganan error untuk ModelArmorSanitizePromptRunnable; True atau False.

  • SANITIZE_RESPONSE_ERROR_HANDLING: boolean yang mengontrol penanganan error untuk ModelArmorSanitizeResponseRunnable; True atau False.

    Saat menangani error, Model Armor berperilaku sebagai berikut:

    • True: mencatat peringatan, tetapi mengizinkan konten lolos meskipun risiko terdeteksi.
    • False: memunculkan ValueError dan memblokir eksekusi saat konten tidak aman terdeteksi.

Konfigurasi ini memastikan bahwa meskipun agen mengeksekusi penalaran multi-langkah atau penggunaan alat, input dan output akan disaring.

Pemeriksaan dokumen

Anda dapat menggunakan runnable Model Armor untuk memeriksa dokumen yang diupload sebelum memprosesnya. Hal ini penting untuk alur kerja seperti perangkuman, yang dokumen sumbernya mungkin berisi konten berbahaya tersembunyi. Anda dapat memuat konten file dan meneruskannya melalui ModelArmorSanitizePromptRunnable sebelum mengirimkannya ke LLM.

Penanganan peristiwa kustom

Untuk kemampuan pengamatan, runnable mengirimkan peristiwa on_model_armor_finding saat konten tidak aman terdeteksi. Anda dapat melampirkan handler callback kustom untuk mencatat detail tertentu (seperti temuan dan konten) atau memicu pemberitahuan tanpa mengganggu alur aplikasi.

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()]})