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

static print_summary(result: Dict)[source]

打印评估摘要

Parameters:

result – evaluate() 返回的结果字典

static save_results(result: Dict, output_path: str)[source]

保存评估结果到 JSONL 文件

Parameters:
  • result – evaluate() 返回的结果字典

  • output_path – 输出文件路径

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

static print_summary(result: Dict)[source]

打印评估摘要

Parameters:

result – evaluate() 返回的结果字典

static save_results(result: Dict, output_path: str)[source]

保存评估结果到 JSONL 文件

Parameters:
  • result – evaluate() 返回的结果字典

  • output_path – 输出文件路径

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:
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]

get_item(idx: int) → Dict[source]

获取单个数据项

Parameters:

idx – 数据索引

Returns:

数据项(包含 query, target, category 等字段)

Return type:

Dict

summary() → Dict[source]

返回数据集摘要信息

Returns:

包含样本数、字段列表、类别分布等

Return type:

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:

BenchmarkDataset

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:
data: List[Dict]
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]

get_item(idx: int) → Dict[source]

获取单个数据项

Parameters:

idx – 数据索引

Returns:

数据项(包含 query, target, category 等字段)

Return type:

Dict

summary() → Dict[source]

返回数据集摘要信息

Returns:

包含样本数、字段列表、类别分布等

Return type:

Dict

Attack Preparation