LangChain과 통합

LangChain 악의적인 입력을 방지하고, 콘텐츠 안전을 확인하고, AI 애플리케이션 전반에서 보안 정책을 일관되게 적용하려면 LangChain 워크플로에 Model Armor를 추가하세요.

시작하기 전에

코드를 구현하기 전에 다음 Google Cloud 설정 단계를 완료하세요.

실행 가능 항목

LangChain과 함께 Model Armor를 사용하려면 표준 LangChain 인터페이스에 맞는 두 가지 기본 실행 가능 항목이 필요합니다.

  • ModelArmorSanitizePromptRunnable: 이 구성요소는 LLM에 도달하기 전에 사용자 입력(프롬프트)을 검사합니다. 악의적인 입력 또는 정책 위반을 감지합니다.

  • ModelArmorSanitizeResponseRunnable: 이 구성요소는 LLM에서 생성된 출력을 사용자에게 반환하기 전에 검사합니다. 기본 보안 검사 후 사용자가 대답에 적용하는 수정사항은 필터링되지 않으며 원시 상태로 사용자에게 전달됩니다.

필수 Python 패키지 설치

다음 Python 패키지를 설치합니다.

  • langchain-google-community 버전 3.0.4 이상
  • langchain-google-genai
pip install langchain-google-community langchain-google-genai

사용 패턴

기본 체이닝 또는 미들웨어를 사용하여 LangChain과 함께 Model Armor를 사용할 수 있습니다.

기본 체이닝

Model Armor를 사용하는 가장 일반적인 방법은 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}")

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트 ID입니다. Google Cloud
  • LOCATION: 템플릿의 위치입니다.
  • TEMPLATE_ID: 시작하기 전에에서 만든 Model Armor 템플릿의 ID입니다.
  • SANITIZE_PROMPT_ERROR_HANDLING: ModelArmorSanitizePromptRunnable의 오류 처리를 제어하는 불리언입니다. True 또는 False입니다.

  • SANITIZE_RESPONSE_ERROR_HANDLING: ModelArmorSanitizeResponseRunnable의 오류 처리를 제어하는 불리언입니다. True 또는 False입니다.

    오류를 처리할 때 Model Armor는 다음과 같이 동작합니다.

    • True: 위험이 감지되더라도 경고를 로깅하지만 콘텐츠가 전달되도록 허용합니다.
    • False: 안전하지 않은 콘텐츠가 감지되면 ValueError를 발생시키고 실행을 차단합니다.

상담사를 위한 미들웨어

도구를 사용하는 LangChain 상담사의 경우 ModelArmorMiddleware를 사용할 수 있습니다. 이 미들웨어는 LangChain 상담사가 도구를 사용할 때 거치는 다양한 상호작용 지점에 관련 정리기 실행 가능 항목을 적용합니다.

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

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트 ID입니다. Google Cloud
  • LOCATION: 템플릿의 위치입니다.
  • TEMPLATE_ID: 시작하기 전에에서 만든 Model Armor 템플릿의 ID입니다.
  • SANITIZE_PROMPT_ERROR_HANDLING: ModelArmorSanitizePromptRunnable의 오류 처리를 제어하는 불리언입니다. True 또는 False입니다.

  • SANITIZE_RESPONSE_ERROR_HANDLING: ModelArmorSanitizeResponseRunnable의 오류 처리를 제어하는 불리언입니다. True 또는 False입니다.

    오류를 처리할 때 Model Armor는 다음과 같이 동작합니다.

    • True: 위험이 감지되더라도 경고를 로깅하지만 콘텐츠가 전달되도록 허용합니다.
    • False: 안전하지 않은 콘텐츠가 감지되면 ValueError를 발생시키고 실행을 차단합니다.

이 설정을 사용하면 상담사가 다단계 추론 또는 도구 사용을 실행하는 경우에도 입력과 출력이 검사됩니다.

문서 검사

Model Armor 실행 가능 항목을 사용하여 업로드된 문서를 처리하기 전에 검사할 수 있습니다. 이는 소스 문서에 숨겨진 악성 콘텐츠가 포함될 수 있는 요약과 같은 워크플로에 필수적입니다. 파일 콘텐츠를 로드하고 LLM에 전송하기 전에 ModelArmorSanitizePromptRunnable을 통해 전달할 수 있습니다.

커스텀 이벤트 처리

관찰 가능성을 위해 실행 가능 항목은 안전하지 않은 콘텐츠가 감지되면 on_model_armor_finding 이벤트를 디스패치합니다. 커스텀 콜백 핸들러를 연결하여 애플리케이션 흐름을 중단하지 않고 특정 세부정보 (예: 발견 및 콘텐츠)를 로깅하거나 알림을 트리거할 수 있습니다.

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