Safety
API reference for safety evaluation, attacks, and scorers.
Attack Integration
Evaluation
包装 AISafetyLab Scorer,提供简单的 evaluate() 接口
设计原则: - 黑箱调用 AISafetyLab 的 scorer.batch_score() - 统一的返回格式(scores, asr, details) - 支持多种 scorer 切换 - 打印友好的统计摘要
- class safety.evaluator.SafetyEvaluator(scorer_name: str = 'llama_guard_3', scorer_model_path: str | None = None, device: str = 'cuda:0', **kwargs)[source]
Bases:
object黑箱包装 AISafetyLab Scorer,提供统一的评估接口
- 支持的 scorer:
llama_guard_3 (推荐): 14 类细粒度分类
harmbench: HarmBench 官方分类器
pattern: 快速正则匹配(仅用于调试)
- 示例:
evaluator = SafetyEvaluator(scorer_name=”llama_guard_3”) result = evaluator.evaluate(queries, responses) evaluator.print_summary(result)
- SUPPORTED_SCORERS = {'deepseek_judge': {'class_name': None, 'default_path': None, 'description': 'LLM judge via DeepSeek v3.2 (1-5 scale, ASR=score>=2)', 'module': None}, 'harmbench': {'class_name': 'HarmBenchScorer', 'default_path': 'cais/HarmBench-Llama-2-13b-cls', 'description': 'HarmBench official binary classifier', 'module': 'aisafetylab.evaluation.scorers'}, 'llama_guard_3': {'class_name': 'LlamaGuard3Scorer', 'default_path': 'meta-llama/Llama-Guard-3-8B', 'description': '14-category fine-grained safety classifier (recommended)', 'module': 'aisafetylab.evaluation.scorers'}, 'pattern': {'class_name': 'PatternScorer', 'default_path': None, 'description': 'Fast regex-based pattern matcher (for debugging only)', 'module': 'aisafetylab.evaluation.scorers'}}
- __init__(scorer_name: str = 'llama_guard_3', scorer_model_path: str | None = None, device: str = 'cuda:0', **kwargs)[source]
- Parameters:
scorer_name – 评估器名称 (“llama_guard_3”, “harmbench”, “pattern”)
scorer_model_path – 模型路径(None 使用默认)
device – 推理设备
**kwargs – 传递给 scorer 构造函数的其他参数
- evaluate(queries: List[str], responses: List[str], batch_size: int = 8, return_details: bool = True) Dict[source]
批量评估
- Parameters:
queries – 问题列表
responses – 回复列表(与 queries 一一对应)
batch_size – scorer 推理批次大小
return_details – 是否返回详细信息
- Returns:
- 包含以下字段
scores: List[int] 每个样本的分数 (0=safe, 1=unsafe)
asr: float 攻击成功率(不安全比例)
total: int 总样本数
unsafe_count: int 不安全样本数
safe_count: int 安全样本数
details: List[Dict] 每条样本的详细结果(if return_details)
scorer: str scorer 名称
- Return type:
Dict
- evaluate_from_file(input_file: str, query_field: str = 'query', response_field: str = 'response', batch_size: int = 8) Dict[source]
从 JSONL 文件加载 queries 和 responses 并评估
- Parameters:
input_file – JSONL 文件路径
query_field – query 字段名
response_field – response 字段名
batch_size – scorer 批次大小
- Returns:
评估结果
- Return type:
Dict
- safety.evaluator.evaluate_queries(queries: List[str], responses: List[str], scorer_name: str = 'llama_guard_3', scorer_model_path: str | None = None, device: str = 'cuda:0', batch_size: int = 8, verbose: bool = True, save_path: str | None = None, **kwargs) Dict[source]
一行代码评估 queries 和 responses
Example
- result = evaluate_queries(
queries=[“q1”, “q2”], responses=[“r1”, “r2”], scorer_name=”llama_guard_3”
) print(f”ASR: {result[‘asr’]:.2%}”)
- Parameters:
queries – 问题列表
responses – 回复列表
scorer_name – 评估器名称
scorer_model_path – 模型路径(可选)
device – 设备
batch_size – 批次大小
verbose – 是否打印摘要
save_path – 保存结果路径(可选)
**kwargs – 传递给 SafetyEvaluator 的额外参数(如 deepseek_judge 配置)
- Returns:
评估结果
- Return type:
Dict
- safety.evaluator.evaluate_from_file(input_file: str, scorer_name: str = 'llama_guard_3', query_field: str = 'query', response_field: str = 'response', **kwargs) Dict[source]
从 JSONL 文件评估(便利函数)
- Parameters:
input_file – JSONL 文件路径
scorer_name – 评估器名称
query_field – query 字段名
response_field – response 字段名
**kwargs – 传递给 SafetyEvaluator.evaluate_from_file 的参数
- Returns:
评估结果
- Return type:
Dict
- class safety.evaluator.SafetyEvaluator(scorer_name: str = 'llama_guard_3', scorer_model_path: str | None = None, device: str = 'cuda:0', **kwargs)[source]
黑箱包装 AISafetyLab Scorer,提供统一的评估接口
- 支持的 scorer:
llama_guard_3 (推荐): 14 类细粒度分类
harmbench: HarmBench 官方分类器
pattern: 快速正则匹配(仅用于调试)
- 示例:
evaluator = SafetyEvaluator(scorer_name=”llama_guard_3”) result = evaluator.evaluate(queries, responses) evaluator.print_summary(result)
- SUPPORTED_SCORERS = {'deepseek_judge': {'class_name': None, 'default_path': None, 'description': 'LLM judge via DeepSeek v3.2 (1-5 scale, ASR=score>=2)', 'module': None}, 'harmbench': {'class_name': 'HarmBenchScorer', 'default_path': 'cais/HarmBench-Llama-2-13b-cls', 'description': 'HarmBench official binary classifier', 'module': 'aisafetylab.evaluation.scorers'}, 'llama_guard_3': {'class_name': 'LlamaGuard3Scorer', 'default_path': 'meta-llama/Llama-Guard-3-8B', 'description': '14-category fine-grained safety classifier (recommended)', 'module': 'aisafetylab.evaluation.scorers'}, 'pattern': {'class_name': 'PatternScorer', 'default_path': None, 'description': 'Fast regex-based pattern matcher (for debugging only)', 'module': 'aisafetylab.evaluation.scorers'}}
- __init__(scorer_name: str = 'llama_guard_3', scorer_model_path: str | None = None, device: str = 'cuda:0', **kwargs)[source]
- Parameters:
scorer_name – 评估器名称 (“llama_guard_3”, “harmbench”, “pattern”)
scorer_model_path – 模型路径(None 使用默认)
device – 推理设备
**kwargs – 传递给 scorer 构造函数的其他参数
- evaluate(queries: List[str], responses: List[str], batch_size: int = 8, return_details: bool = True) Dict[source]
批量评估
- Parameters:
queries – 问题列表
responses – 回复列表(与 queries 一一对应)
batch_size – scorer 推理批次大小
return_details – 是否返回详细信息
- Returns:
- 包含以下字段
scores: List[int] 每个样本的分数 (0=safe, 1=unsafe)
asr: float 攻击成功率(不安全比例)
total: int 总样本数
unsafe_count: int 不安全样本数
safe_count: int 安全样本数
details: List[Dict] 每条样本的详细结果(if return_details)
scorer: str scorer 名称
- Return type:
Dict
- evaluate_from_file(input_file: str, query_field: str = 'query', response_field: str = 'response', batch_size: int = 8) Dict[source]
从 JSONL 文件加载 queries 和 responses 并评估
- Parameters:
input_file – JSONL 文件路径
query_field – query 字段名
response_field – response 字段名
batch_size – scorer 批次大小
- Returns:
评估结果
- Return type:
Dict
Datasets
从 AISafetyLab 加载评测数据集,提取纯 queries 列表
设计原则: - 只作为 AISafetyLab AttackDataset 的黑箱包装器 - 不修改 AISafetyLab 任何代码 - 当前仅支持 HarmBench 数据集(使用标准 split ‘standard’)
- 用法:
from safety import BenchmarkDataset ds = BenchmarkDataset(“harmbench”) queries = ds.get_queries()
- class safety.dataset.BenchmarkDataset(dataset_name: str, data_path: str | None = None)[source]
Bases:
object数据集加载器,当前仅支持 HarmBench
- 示例:
ds = BenchmarkDataset(“harmbench”) print(f”Loaded {len(ds)} queries”) print(ds[0][‘query’]) # 第一个问题
- SUPPORTED_DATASETS = ['harmbench']
- __init__(dataset_name: str, data_path: str | None = None)[source]
- Parameters:
dataset_name – 数据集名称,目前只支持 “harmbench”
data_path – 未使用,保留供未来扩展
- Raises:
ValueError – 数据集不支持
RuntimeError – 下载或加载失败
- get_queries() List[str][source]
返回纯 query 字符串列表,用于推理
- Returns:
所有样本的 query 字段
- Return type:
List[str]
- get_items() List[Dict][source]
返回原始数据项列表(含 query 及其他字段如 category、target 等)
- Returns:
原始数据字典列表
- Return type:
List[Dict]
- safety.dataset.load_benchmark(dataset: str, max_samples: int | None = None) BenchmarkDataset[source]
快速加载评测数据集的便利函数
Example
>>> ds = load_benchmark("harmbench", max_samples=10) >>> queries = ds.get_queries()
- Parameters:
dataset – 数据集名称
max_samples – 限制最大样本数(用于快速测试)
- Returns:
数据集对象
- Return type:
- class safety.dataset.BenchmarkDataset(dataset_name: str, data_path: str | None = None)[source]
数据集加载器,当前仅支持 HarmBench
- 示例:
ds = BenchmarkDataset(“harmbench”) print(f”Loaded {len(ds)} queries”) print(ds[0][‘query’]) # 第一个问题
- SUPPORTED_DATASETS = ['harmbench']
- __init__(dataset_name: str, data_path: str | None = None)[source]
- Parameters:
dataset_name – 数据集名称,目前只支持 “harmbench”
data_path – 未使用,保留供未来扩展
- Raises:
ValueError – 数据集不支持
RuntimeError – 下载或加载失败
- get_queries() List[str][source]
返回纯 query 字符串列表,用于推理
- Returns:
所有样本的 query 字段
- Return type:
List[str]
- get_items() List[Dict][source]
返回原始数据项列表(含 query 及其他字段如 category、target 等)
- Returns:
原始数据字典列表
- Return type:
List[Dict]