LangChain과 함께 Model Armor를 사용하여 LLM 프롬프트와 대답을 선제적으로 검사하여 AI 애플리케이션의 보안을 강화하세요. 악의적인 입력을 방지하고, 콘텐츠 안전을 확인하고, AI 애플리케이션 전반에서 보안 정책을 일관되게 적용하려면 LangChain 워크플로에 Model Armor를 추가하세요.
시작하기 전에
코드를 구현하기 전에 다음 Google Cloud 설정 단계를 완료하세요.
- 프로젝트를 선택하거나 만들고 결제를 사용 설정합니다.
- 프로젝트에서 Model Armor API를 사용 설정합니다.
gcloud를 사용하거나GOOGLE_APPLICATION_CREDENTIALS환경 변수를 설정하여 인증을 설정합니다.- 서비스 계정에 Model Armor 사용자(
roles/modelarmor.user) 역할이 있는지 확인합니다. 템플릿을 관리하려면 Model Armor 관리자(roles/modelarmor.admin) 역할이 필요합니다. - 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 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}")
다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.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 에이전트가 거치는 다양한 상호작용 지점에서 관련 sanitizer runnable을 적용합니다.
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: Google Cloud 프로젝트 ID입니다.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()]})