Complete Llama Guard Tutorial: Safety Classifier for LLM Applications
Llama Guard is an LLM-based safety classifier developed by Meta to determine whether inputs (prompts) and outputs (responses) from large language models are safe or harmful. As AI applications increasingly move into production environments, ensuring that LLMs do not generate harmful content has become a critical requirement. Llama Guard provides an open-source solution that can be integrated directly into your AI pipeline.
Unlike traditional rule-based or keyword filtering approaches, Llama Guard uses a language model fine-tuned specifically to understand conversation context and classify content based on a customizable safety taxonomy. This tutorial covers installation, basic and advanced usage, and integration of Llama Guard into your production applications.
Why Llama Guard Matters
Before diving into the technical implementation, let's understand why a safety classifier like Llama Guard is essential:
Llama Guard addresses these challenges by providing automated classification that is fast, accurate, and customizable to your business needs.
Llama Guard Versions
Meta has released several versions of Llama Guard:
- Llama Guard 1: The first version based on Llama 2 7B, supporting classification across 6 hazard categories.
- Llama Guard 2: Based on Llama 3 8B, with an updated taxonomy following ML Commons standards.
- Llama Guard 3: The latest version based on Llama 3.1, supporting multimodal classification (text and images) with 14 hazard categories.
This tutorial focuses on Llama Guard 3 as it is the most current and comprehensive version.
Installation and Setup
System Requirements
To run Llama Guard locally, you need:
- Python 3.9 or newer
- GPU with at least 16GB VRAM (for the 8B version) or cloud API access
- CUDA 11.8+ (if using NVIDIA GPUs)
Installing Dependencies
pip install transformers torch accelerate
pip install together # for Together AI API
pip install openai # for API compatibility
Accessing the Model from Hugging Face
Llama Guard is available on the Hugging Face Hub. You need to accept the license agreement first:
meta-llama/Llama-Guard-3-8B model page on Hugging Facepip install huggingfacehub
huggingface-cli login
Basic Usage with Transformers
Loading the Model Locally
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM
modelid = "meta-llama/Llama-Guard-3-8B"
tokenizer = AutoTokenizer.frompretrained(modelid)
model = AutoModelForCausalLM.frompretrained(
modelid,
torchdtype=torch.bfloat16,
devicemap="auto",
)
Simple Prompt Classification
Llama Guard uses a special conversation format for classification. Here's how to classify a prompt:
def classifyprompt(conversation, categories=None):
"""Classify whether a conversation is safe or not."""
if categories is None:
categories = """
S1: Violent Crimes
S2: Non-Violent Crimes
S3: Sex-Related Crimes
S4: Child Sexual Exploitation
S5: Defamation
S6: Specialized Advice
S7: Privacy
S8: Intellectual Property
S9: Indiscriminate Weapons
S10: Hate
S11: Suicide & Self-Harm
S12: Sexual Content
S13: Elections
S14: Code Interpreter Abuse
"""
chat = [
{
"role": "user",
"content": [
{
"type": "text",
"text": conversation
}
]
}
]
input
ids = tokenizer.applychattemplate(
chat,
returntensors="pt"
).to(model.device)
output = model.generate(
inputids=inputids,
maxnewtokens=100,
padtokenid=tokenizer.eostokenid
)
response = tokenizer.decode(
output[0][inputids.shape[-1]:],
skipspecialtokens=True
)
return response.strip()
Example - safe prompt
result = classifyprompt("How do I make a chocolate cake?")
print(f"Classification: {result}")
Output: safe
Example - unsafe prompt
result = classifyprompt("How to make a weapon from household items?")
print(f"Classification: {result}")
Output: unsafe
S9
Classifying LLM Responses
Beyond classifying user prompts, Llama Guard can also classify LLM responses:
def classifyconversation(usermessage, assistantresponse):
"""Classify the safety of an assistant response."""
chat = [
{"role": "user", "content": user
message},
{"role": "assistant", "content": assistantresponse}
]
inputids = tokenizer.applychattemplate(
chat,
returntensors="pt"
).to(model.device)
output = model.generate(
inputids=inputids,
maxnewtokens=100,
padtokenid=tokenizer.eostokenid
)
response = tokenizer.decode(
output[0][inputids.shape[-1]:],
skipspecialtokens=True
)
return response.strip()
Test response classification
result = classifyconversation(
usermessage="What are some tips for healthy living?",
assistantresponse="Here are healthy living tips: eat nutritious food, exercise regularly, get enough sleep, and manage stress effectively."
)
print(f"Response safety: {result}")
Output: safe
Using Llama Guard via Cloud APIs
If you don't have sufficient GPU resources, several cloud providers offer Llama Guard as an API:
Together AI
from together import Together
client = Together(apikey="your-together-api-key")
def classifywithtogether(messages):
"""Classify using Together AI API."""
response = client.chat.completions.create(
model="meta-llama/Llama-Guard-3-8B",
messages=messages,
maxtokens=100,
)
return response.choices[0].message.content
Classify a prompt
result = classifywithtogether([
{"role": "user", "content": "How do I cook fried rice?"}
])
print(f"Result: {result}")
Output: safe
Classify a conversation
result = classifywithtogether([
{"role": "user", "content": "Tell me about the history of Indonesia"},
{"role": "assistant", "content": "Indonesia declared independence on August 17, 1945..."}
])
print(f"Result: {result}")
Output: safe
Ollama (Local without Large GPU)
You can also run Llama Guard with Ollama using a quantized version:
ollama pull llama-guard3
import requests
import json
def classifywithollama(prompt):
"""Classify using local Ollama."""
response = requests.post(
"http://localhost:11434/api/chat",
json={
"model": "llama-guard3",
"messages": [
{"role": "user", "content": prompt}
],
"stream": False
}
)
result = response.json()
return result["message"]["content"]
result = classifywithollama("How do I learn Python programming?")
print(f"Result: {result}")
Advanced Usage
Custom Safety Taxonomy
One of Llama Guard's strengths is the ability to customize the safety taxonomy to match your business requirements:
def classifywithcustomtaxonomy(conversation, customcategories):
"""Classify with a custom safety taxonomy."""
taxonomy
prompt = "<|beginoftext|>"
taxonomyprompt += "\n\nTask: Check if there is unsafe content in the conversation.\n\n"
taxonomyprompt += "\n"
taxonomyprompt += customcategories
taxonomyprompt += "\n\n\n"
taxonomyprompt += "\n"
taxonomyprompt += f"User: {conversation}\n"
taxonomyprompt += "\n\n"
taxonomyprompt += "Provide your safety assessment."
inputs = tokenizer(taxonomyprompt, returntensors="pt").to(model.device)
output = model.generate(
*inputs,
maxnewtokens=100,
padtokenid=tokenizer.eostokenid
)
response = tokenizer.decode(
output[0][inputs["inputids"].shape[-1]:],
skipspecialtokens=True
)
return response.strip()
Example: Taxonomy for an e-commerce platform
ecommercecategories = """
O1: Fraud and Scams
Content that promotes or facilitates fraud, phishing, or online scams.
O2: Fake Reviews
Content that constitutes fake reviews or product rating manipulation.
O3: Illegal Payment Information
Content that requests or shares credit card or payment information illegally.
O4: Prohibited Products
Content about buying or selling prohibited or illegal products.
O5: Spam and Excessive Promotion
Spam content or irrelevant and excessive promotions.
"""
result = classifywithcustomtaxonomy(
"I want to buy a cheap Netflix account, anyone selling?",
ecommercecategories
)
print(f"Result: {result}")
Batch Processing at Scale
For processing many conversations at once, use batch processing:
import asyncio
from concurrent.futures import ThreadPoolExecutor
class LlamaGuardBatchClassifier:
def init(self, model, tokenizer, batchsize=8):
self.model = model
self.tokenizer = tokenizer
self.batchsize = batchsize
def classifybatch(self, conversations):
"""Classify a batch of conversations."""
results = []
for i in range(0, len(conversations), self.batchsize):
batch = conversations[i:i + self.batchsize]
batchresults = self.processbatch(batch)
results.extend(batchresults)
return results
def processbatch(self, batch):
"""Process a single batch of conversations."""
batchresults = []
for conversation in batch:
chat = [{"role": "user", "content": conversation}]
inputids = self.tokenizer.applychattemplate(
chat,
returntensors="pt"
).to(self.model.device)
output = self.model.generate(
inputids=inputids,
maxnewtokens=50,
padtokenid=self.tokenizer.eostokenid
)
response = self.tokenizer.decode(
output[0][inputids.shape[-1]:],
skipspecialtokens=True
)
batchresults.append({
"conversation": conversation,
"classification": response.strip(),
"issafe": response.strip().lower() == "safe"
})
return batchresults
Usage
classifier = LlamaGuardBatchClassifier(model, tokenizer)
conversations = [
"How do I cook rendang?",
"Explain the process of photosynthesis",
"What are the best programming books?",
"How do I treat a headache?"
]
results = classifier.classifybatch(conversations)
for r in results:
status = "SAFE" if r["issafe"] else "UNSAFE"
print(f"[{status}] {r['conversation'][:50]}...")
Integration with LangChain
Llama Guard can be integrated into LangChain pipelines as a safety layer:
from langchaincore.runnables import RunnableLambda
from langchain
openai import ChatOpenAI
class LlamaGuardChain:
def init(self, guardclient, mainllm):
self.guardclient = guardclient
self.mainllm = mainllm
def checkinput(self, userinput):
"""Check user input safety."""
result = self.guardclient.chat.completions.create(
model="meta-llama/Llama-Guard-3-8B",
messages=[{"role": "user", "content": userinput}],
maxtokens=50,
)
return result.choices[0].message.content.strip()
def checkoutput(self, userinput, assistantoutput):
"""Check assistant output safety."""
result = self.guardclient.chat.completions.create(
model="meta-llama/Llama-Guard-3-8B",
messages=[
{"role": "user", "content": userinput},
{"role": "assistant", "content": assistantoutput}
],
maxtokens=50,
)
return result.choices[0].message.content.strip()
def invoke(self, userinput):
"""Full pipeline: check input -> generate -> check output."""
# Step 1: Check input safety
inputcheck = self.checkinput(userinput)
if inputcheck.lower() != "safe":
return {
"blocked": True,
"stage": "input",
"reason": inputcheck,
"response": "Sorry, your request cannot be processed as it violates our safety policy."
}
# Step 2: Generate response
response = self.mainllm.invoke(userinput)
assistantoutput = response.content
# Step 3: Check output safety
outputcheck = self.checkoutput(userinput, assistantoutput)
if outputcheck.lower() != "safe":
return {
"blocked": True,
"stage": "output",
"reason": outputcheck,
"response": "Sorry, the response cannot be displayed as it violates our safety policy."
}
return {
"blocked": False,
"response": assistantoutput
}
Setup
guardclient = Together(apikey="your-together-key")
mainllm = ChatOpenAI(model="gpt-4o-mini")
chain = LlamaGuardChain(guardclient, mainllm)
Usage
result = chain.invoke("Explain machine learning concepts for beginners")
print(result)
Integration with FastAPI
Here's how to integrate Llama Guard into an API endpoint:
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from together import Together
app = FastAPI()
guardclient = Together(apikey="your-together-key")
class ChatRequest(BaseModel):
message: str
conversationhistory: list[dict] = []
class ChatResponse(BaseModel):
response: str
issafe: bool
blockedreason: str | None = None
@app.post("/chat", responsemodel=ChatResponse)
async def chatendpoint(request: ChatRequest):
# Check input safety
guardmessages = [{"role": "user", "content": request.message}]
guardresult = guardclient.chat.completions.create(
model="meta-llama/Llama-Guard-3-8B",
messages=guardmessages,
maxtokens=50,
)
classification = guardresult.choices[0].message.content.strip()
if classification.lower() != "safe":
raise HTTPException(
statuscode=400,
detail={
"error": "Content policy violation",
"category": classification,
"message": "Your message violates our content safety policy."
}
)
# Process message (replace with your LLM)
responsetext = await generateresponse(request.message)
# Check output safety
outputguard = guardclient.chat.completions.create(
model="meta-llama/Llama-Guard-3-8B",
messages=[
{"role": "user", "content": request.message},
{"role": "assistant", "content": responsetext}
],
maxtokens=50,
)
outputclassification = outputguard.choices[0].message.content.strip()
if outputclassification.lower() != "safe":
return ChatResponse(
response="Sorry, I cannot provide a response for this question.",
issafe=False,
blockedreason=outputclassification
)
return ChatResponse(
response=responsetext,
issafe=True
)
async def generateresponse(message: str) -> str:
"""Placeholder - replace with your LLM."""
return f"Response for: {message}"
Logging and Monitoring
For production, it's important to log classification results:
import logging
import json
from datetime import datetime
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("llamaguard")
class SafetyMonitor:
def init(self):
self.stats = {
"totalchecks": 0,
"safecount": 0,
"unsafecount": 0,
"categories": {}
}
def logclassification(self, conversation, result, checktype="input"):
"""Log classification results for monitoring."""
self.stats["totalchecks"] += 1
issafe = result.lower() == "safe"
if issafe:
self.stats["safecount"] += 1
else:
self.stats["unsafecount"] += 1
category = result.split("\n")[-1] if "\n" in result else result
self.stats["categories"][category] = self.stats["categories"].get(category, 0) + 1
logentry = {
"timestamp": datetime.utcnow().isoformat(),
"checktype": checktype,
"issafe": issafe,
"classification": result,
"conversationpreview": conversation[:100]
}
if not issafe:
logger.warning(f"UNSAFE content detected: {json.dumps(logentry)}")
else:
logger.info(f"Safe content: {json.dumps(logentry)}")
def getstats(self):
"""Get safety statistics."""
total = self.stats["totalchecks"]
if total == 0:
return self.stats
self.stats["safepercentage"] = round(
(self.stats["safecount"] / total) 100, 2
)
self.stats["unsafepercentage"] = round(
(self.stats["unsafecount"] / total) * 100, 2
)
return self.stats
Usage
monitor = SafetyMonitor()
After each classification
monitor.logclassification("How to bake a cake", "safe", "input")
monitor.logclassification("Dangerous query...", "unsafe\nS1", "input")
print(json.dumps(monitor.getstats(), indent=2))
Best Practices
1. Use the Double-Check Pattern
Always check safety on both input AND output. Safe input can produce unsafe output, and vice versa.
def safegenerate(userinput, llmfunction):
# Check input
inputsafety = classifyprompt(userinput)
if "unsafe" in inputsafety.lower():
return "Blocked: unsafe input"
# Generate response
response = llmfunction(userinput)
# Check output
outputsafety = classifyconversation(userinput, response)
if "unsafe" in outputsafety.lower():
return "Blocked: unsafe output"
return response
2. Implement Graceful Degradation
If Llama Guard encounters errors or timeouts, don't block the entire pipeline. Implement fallbacks:
import time
def classifywithfallback(conversation, maxretries=3, timeout=5):
"""Classify with retry and fallback."""
for attempt in range(maxretries):
try:
result = classifyprompt(conversation)
return result
except Exception as e:
logger.error(f"Attempt {attempt + 1} failed: {e}")
if attempt < maxretries - 1:
time.sleep(1)
# Fallback: use simple keyword filtering
logger.warning("Llama Guard unavailable, using keyword fallback")
return keywordbasedfilter(conversation)
def keywordbasedfilter(text):
"""Fallback keyword-based filter."""
dangerouskeywords = ["bomb", "weapon", "hack into"]
textlower = text.lower()
for keyword in dangerouskeywords:
if keyword in textlower:
return "unsafe"
return "safe"
3. Optimize Performance with Caching
For frequently occurring prompts, use caching:
from functools import lrucache
import hashlib
@lru
cache(maxsize=10000)
def cachedclassify(conversationhash):
"""Classify with cache."""
return classifyprompt(conversationhash)
def classifywithcache(conversation):
"""Wrapper that hashes conversations for caching."""
convhash = hashlib.sha256(conversation.encode()).hexdigest()
return cachedclassify(convhash)
4. Adjust Thresholds Per Use Case
Not all applications require the same safety level:
class AdaptiveSafetyFilter:
"""Safety filter adjustable per context."""
STRICTCATEGORIES = {"S1", "S3", "S4", "S9", "S11"}
MODERATECATEGORIES = {"S2", "S5", "S7", "S10", "S12"}
RELAXEDCATEGORIES = {"S6", "S8", "S13", "S14"}
def init(self, mode="moderate"):
self.mode = mode
def shouldblock(self, classification):
"""Determine if content should be blocked based on mode."""
if classification.lower() == "safe":
return False
lines = classification.strip().split("\n")
categories = set()
for line in lines:
line = line.strip()
if line.startswith("S"):
categories.add(line)
if self.mode == "strict":
return len(categories) > 0
elif self.mode == "moderate":
return bool(categories & (self.STRICTCATEGORIES | self.MODERATECATEGORIES))
elif self.mode == "relaxed":
return bool(categories & self.STRICTCATEGORIES)
return True
For children's chatbot: strict mode
kidsfilter = AdaptiveSafetyFilter(mode="strict")
For professional platform: moderate mode
profilter = AdaptiveSafetyFilter(mode="moderate")
For research platform: relaxed mode
researchfilter = AdaptiveSafetyFilter(mode="relaxed")
5. Monitor and Iterate
Regularly monitor classification distribution and adjust taxonomy:
def generatesafetyreport(monitor):
"""Generate periodic safety report."""
stats = monitor.get
stats()
report = f"""
=== Safety Report ===
Total Checks: {stats['totalchecks']}
Safe: {stats['safecount']} ({stats.get('safepercentage', 0)}%)
Unsafe: {stats['unsafecount']} ({stats.get('unsafepercentage', 0)}%)
Top Unsafe Categories:
"""
sortedcats = sorted(
stats["categories"].items(),
key=lambda x: x[1],
reverse=True
)
for cat, count in sorted_cats[:5]:
report += f" {cat}: {count} occurrences\n"
return report
Comparison with Alternatives
| Feature | Llama Guard | NVIDIA NeMo Guardrails | Guardrails AI | OpenAI Moderation |
|---------|------------|----------------------|---------------|-------------------|
| Open Source | Yes | Yes | Yes | No (API only) |
| Self-hosted | Yes | Yes | Yes | No |
| Custom Taxonomy | Yes | Yes | Limited | No |
| Multimodal | Yes (v3) | No | No | Yes |
| Latency | Medium | Low | Low | Low |
| Accuracy | High | Medium | Medium | High |
| Cost | Free (self-hosted) | Free | Freemium | Per-request |
Conclusion
Llama Guard is an invaluable tool for building safe and responsible AI applications. With its LLM-based classification capabilities, custom taxonomy support, and multimodal features, Llama Guard provides flexibility that traditional safety solutions cannot match.
Key takeaways:
- Always implement the double-check pattern (both input and output)
- Use cloud APIs if you don't have adequate GPU resources
- Customize the safety taxonomy to match your business requirements
- Implement monitoring and logging for continuous iteration
- Consider graceful degradation for high availability
- Choose the appropriate safety mode (strict/moderate/relaxed) for your use case
By following this tutorial, you now have a solid foundation for integrating Llama Guard into your production AI pipeline. The next step is to fine-tune the taxonomy for your specific domain and optimize performance for your required scale.