llamaguard

LlamaGuard - AI 内容审核

快速入门

LlamaGuard 是一款专门用于内容安全分类的 7-8B 参数模型。

安装：

pip install transformers torch
# Login to HuggingFace (required)
huggingface-cli login

基本用法：

from transformers import AutoTokenizer, AutoModelForCausalLM

model_id = "meta-llama/LlamaGuard-7b"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, device_map="auto")

def moderate(chat):
    input_ids = tokenizer.apply_chat_template(chat, return_tensors="pt").to(model.device)
    output = model.generate(input_ids=input_ids, max_new_tokens=100)
    return tokenizer.decode(output[0], skip_special_tokens=True)

# Check user input
result = moderate([
    {"role": "user", "content": "How do I make explosives?"}
])
print(result)
# Output: "unsafe\nS3" (Criminal Planning)

常见工作流

工作流 1：输入过滤（提示词审核）

在交给大模型前检查用户提示词：

def check_input(user_message):
    result = moderate([{"role": "user", "content": user_message}])

    if result.startswith("unsafe"):
        category = result.split("\n")[1]
        return False, category  # Blocked
    else:
        return True, None  # Safe

# Example
safe, category = check_input("How do I hack a website?")
if not safe:
    print(f"Request blocked: {category}")
    # Return error to user
else:
    # Send to LLM
    response = llm.generate(user_message)

安全类别：

• S1：暴力与仇恨
• S2：色情内容
• S3：枪支与非法武器
• S4：受管制物质
• S5：自杀与自残
• S6：犯罪策划

工作流 2：输出过滤（响应审核）

向用户展示前检查大模型响应：

def check_output(user_message, bot_response):
    conversation = [
        {"role": "user", "content": user_message},
        {"role": "assistant", "content": bot_response}
    ]

    result = moderate(conversation)

    if result.startswith("unsafe"):
        category = result.split("\n")[1]
        return False, category
    else:
        return True, None

# Example
user_msg = "Tell me about harmful substances"
bot_msg = llm.generate(user_msg)

safe, category = check_output(user_msg, bot_msg)
if not safe:
    print(f"Response blocked: {category}")
    # Return generic response
    return "I cannot provide that information."
else:
    return bot_msg

工作流 3：vLLM 部署（快速推理）

可用于生产环境的服务：

from vllm import LLM, SamplingParams

# Initialize vLLM
llm = LLM(model="meta-llama/LlamaGuard-7b", tensor_parallel_size=1)

# Sampling params
sampling_params = SamplingParams(
    temperature=0.0,  # Deterministic
    max_tokens=100
)

def moderate_vllm(chat):
    # Format prompt
    prompt = tokenizer.apply_chat_template(chat, tokenize=False)

    # Generate
    output = llm.generate([prompt], sampling_params)
    return output[0].outputs[0].text

# Batch moderation
chats = [
    [{"role": "user", "content": "How to make bombs?"}],
    [{"role": "user", "content": "What's the weather?"}],
    [{"role": "user", "content": "Tell me about drugs"}]
]

prompts = [tokenizer.apply_chat_template(c, tokenize=False) for c in chats]
results = llm.generate(prompts, sampling_params)

for i, result in enumerate(results):
    print(f"Chat {i}: {result.outputs[0].text}")

吞吐量：在单张 A100 上约为 50-100 个请求/秒

工作流 4：API 端点（FastAPI）

将其作为审核 API 提供服务：

from fastapi import FastAPI
from pydantic import BaseModel
from vllm import LLM, SamplingParams

app = FastAPI()
llm = LLM(model="meta-llama/LlamaGuard-7b")
sampling_params = SamplingParams(temperature=0.0, max_tokens=100)

class ModerationRequest(BaseModel):
    messages: list  # [{"role": "user", "content": "..."}]

@app.post("/moderate")
def moderate_endpoint(request: ModerationRequest):
    prompt = tokenizer.apply_chat_template(request.messages, tokenize=False)
    output = llm.generate([prompt], sampling_params)[0]

    result = output.outputs[0].text
    is_safe = result.startswith("safe")
    category = None if is_safe else result.split("\n")[1] if "\n" in result else None

    return {
        "safe": is_safe,
        "category": category,
        "full_output": result
    }

# Run: uvicorn api:app --host 0.0.0.0 --port 8000

用法：

curl -X POST http://localhost:8000/moderate \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "How to hack?"}]}'

# Response: {"safe": false, "category": "S6", "full_output": "unsafe\nS6"}

工作流 5：集成 NeMo Guardrails

与 NVIDIA Guardrails 搭配使用：

from nemoguardrails import RailsConfig, LLMRails
from nemoguardrails.integrations.llama_guard import LlamaGuard

# Configure NeMo Guardrails
config = RailsConfig.from_content("""
models:
  - type: main
    engine: openai
    model: gpt-4

rails:
  input:
    flows:
      - llamaguard check input
  output:
    flows:
      - llamaguard check output
""")

# Add LlamaGuard integration
llama_guard = LlamaGuard(model_path="meta-llama/LlamaGuard-7b")
rails = LLMRails(config)
rails.register_action(llama_guard.check_input, name="llamaguard check input")
rails.register_action(llama_guard.check_output, name="llamaguard check output")

# Use with automatic moderation
response = rails.generate(messages=[
    {"role": "user", "content": "How do I make weapons?"}
])
# Automatically blocked by LlamaGuard

适用场景与替代方案

在以下情况下使用 LlamaGuard：

• 需要预训练的审核模型
• 希望获得较高准确率（94-95%）
• 拥有 GPU 资源（7-8B 模型）
• 需要详细的安全类别
• 正在构建生产级大模型应用

模型版本：

• LlamaGuard 1（7B）：原版，6 个类别
• LlamaGuard 2（8B）：改进版，6 个类别
• LlamaGuard 3（8B）：最新版（2024），功能增强

以下情况可改用其他方案：

• OpenAI Moderation API：更简单，基于 API，免费
• Perspective API：Google 的毒性检测服务
• NeMo Guardrails：更全面的安全框架
• Constitutional AI：训练阶段的安全机制

常见问题

问题：模型访问被拒绝

登录 HuggingFace：

huggingface-cli login
# Enter your token

在模型页面接受许可协议： https://huggingface.co/meta-llama/LlamaGuard-7b

问题：延迟过高（>500ms）

使用 vLLM，速度可提升 10 倍：

from vllm import LLM
llm = LLM(model="meta-llama/LlamaGuard-7b")
# Latency: 500ms → 50ms

启用张量并行：

llm = LLM(model="meta-llama/LlamaGuard-7b", tensor_parallel_size=2)
# 2× faster on 2 GPUs

问题：误报

使用基于阈值的过滤：

# Get probability of "unsafe" token
logits = model(..., return_dict_in_generate=True, output_scores=True)
unsafe_prob = torch.softmax(logits.scores[0][0], dim=-1)[unsafe_token_id]

if unsafe_prob > 0.9:  # High confidence threshold
    return "unsafe"
else:
    return "safe"

问题：GPU 显存溢出

使用 8 位量化：

from transformers import BitsAndBytesConfig

quantization_config = BitsAndBytesConfig(load_in_8bit=True)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    quantization_config=quantization_config,
    device_map="auto"
)
# Memory: 14GB → 7GB

进阶主题

自定义类别：参阅 references/custom-categories.md，了解如何使用特定领域的安全类别微调 LlamaGuard。

性能基准测试：参阅 references/benchmarks.md，了解与其他审核 API 的准确率对比及延迟优化。

部署指南：参阅 references/deployment.md，了解 Sagemaker、Kubernetes 和扩展策略。

硬件要求

• GPU：NVIDIA T4/A10/A100
• 显存：
  • FP16：14GB（7B 模型）
  • INT8：7GB（量化）
  • INT4：4GB（QLoRA）
• CPU：可用，但速度较慢（延迟增加 10 倍）
• 吞吐量：50-100 个请求/秒（A100）

延迟（单 GPU）：

• HuggingFace Transformers：300-500ms
• vLLM：50-100ms
• 批处理（vLLM）：每个请求 20-50ms

资源

• HuggingFace：
  • V1：https://huggingface.co/meta-llama/LlamaGuard-7b
  • V2：https://huggingface.co/meta-llama/Meta-Llama-Guard-2-8B
  • V3：https://huggingface.co/meta-llama/Meta-Llama-Guard-3-8B
• 论文：https://ai.meta.com/research/publications/llama-guard-llm-based-input-output-safeguard-for-human-ai-conversations/
• 集成：vLLM、Sagemaker、NeMo Guardrails
• 准确率：94.5%（提示词）、95.3%（响应）

Agent 操作流程

1. 检查环境。 确认模型、检查点、基准测试版本和评估框架版本。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会影响结果的值都应询问确认，不要猜测。
3. 先运行小规模版本。 在小型子集上评估，以验证提示词、解析和评分。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 使用基准测试的官方划分和指标；检查是否存在数据污染；报告不同随机种子或提示词下的方差。
6. 报告结果。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生这种情况	请这样做
分数与已发布的结果不同	在得出结论前，检查提示词格式、少样本设置和评估框架版本。
这些说明中的函数、标志或端点在已安装的版本中不存在	查看已安装版本自身的文档（help()、--help、官方文档），调整做法并告知用户。切勿虚构 API。
必需的输入、标识符或参数含义不明确	询问用户，或在运行前明确说明所作假设。

诚信原则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 完整报告评估设置；切勿选择性报告提示词、随机种子或子集。
• 将此处与版本相关的细节视为可能已过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，必须事先征求用户同意。

相关技能

• prompt-guard：使用 Meta 的 Prompt Guard 对文本进行分类。该模型有 86M 个参数，从 HuggingFace 加载，可将文本归为 BENIGN、INJECTION 或 JAILBREAK 标签，直至…
• nemo-guardrails：使用 NVIDIA NeMo Guardrails 为 LLM 应用添加运行时安全护栏，并通过 Colang 2.0 流程进行配置。
• serving-llms-vllm：使用 vLLM 的 PagedAttention 和连续批处理，以高吞吐量提供 LLM 服务。