# 指纹 / 模型安全三件套：功能详解 + 运行手册（llmmap · llm_verify · llm_fingerprint_detector）

> 本文档说明已接入 evalstone 的三个指纹 / 模型安全 benchmark。
> 三者**不经过 EvalScope 数据集管线**，由 `bash/fingerprint/` 下的独立执行器直接探测被测端点，
> 但产出与 EvalScope 同构的报告，`collect_results.py` 可像普通 benchmark 一样汇总进 CSV/Excel。
> 相关代码入口：`bash/run.py` 的 `--suite fingerprint` / `ALL_FINGERPRINT`（`bash/run.py:138`）。
> 理论说明见 `/data1/xii/model_fingerprint_detection.md`，实现注意见 `bash/fingerprint/README.md`。

---

## 目录

- [0. 三件套是什么（30 秒版）](#0-三件套是什么30-秒版)
- [1. 功能详解 / 识别粒度：识别"模型"还是"模型家族"？](#1-功能详解--识别粒度识别模型还是模型家族)
- [2. 支持哪些模型（三件套各自的能力边界）](#2-支持哪些模型三件套各自的能力边界)
- [3. 线上公开数据 / 别人测过的数据](#3-线上公开数据--别人测过的数据)
- [4. 前置条件](#4-前置条件)
- [5. 一条命令跑完三个（fingerprint 套件）](#5-一条命令跑完三个fingerprint-套件)
- [6. 单独跑某一个（含各工具独立用法）](#6-单独跑某一个含各工具独立用法)
- [7. 参数速查表](#7-参数速查表)
- [8. 输出与结果汇总](#8-输出与结果汇总)
- [9. 实测示例](#9-实测示例)
- [10. 常见坑 / 排障](#10-常见坑--排障)
- [11. 参考](#11-参考)

---

## 0. 三件套是什么（30 秒版）

| benchmark | 工具仓库 | 一句话定位 | 得分含义（0~1） |
|---|---|---|---|
| `llmmap` | [LLMmap](/data1/xii/LLMmap) | **模型身份识别**："这段回答是哪个模型写的？"（open-set 检索） | 无 `--expected-model` 时 = 距离置信度；有 = Top-1 身份严格匹配 flag（1.0/0.0） |
| `llm_verify` | [llm-verify](/data1/xii/llm-verify) | **API 欺诈检测**："这个 API 是不是在骗我？"（红旗+裁决） | `NO_FRAUD_SIGNALS`=1.0 / `INCONCLUSIVE`=0.5 / `SUSPICIOUS`=0.25 / `FRAUD_DETECTED`=0.0 |
| `llm_fingerprint_detector` | [llm-fingerprint-detector](/data1/xii/llm-fingerprint-detector) | **单 token 分布验证**："它是不是它声称的那个模型？"（JSD 比对） | `max(0, 1-meanJSD)`；无参考时跑"自一致"模式（采两次互比） |

共同核心思想：把被测端点当成"未知模型"，靠**固定的探测问题 + 回答模式**来认出它 / 判断它有没有撒谎，
而不是相信模型自称的身份。

---

## 1. 功能详解 / 识别粒度：识别"模型"还是"模型家族"？

这是三个工具**本质区别**的地方。先给结论，再逐个展开：

| 工具 | 能识别**精确模型**？ | 能识别**模型家族**？ | 本质工作方式 |
|---|---|---|---|
| **LLMmap** | ✅ 模板库内的模型可精确指认 | ✅ 库外模型可"归族"（最邻近检索，通常落在同家族/同规模附近） | open-set 无监督检索（52 个模板 + 预训练编码器） |
| **LLM Verify** | ❌ 不回答"是谁" | ❌ 不做身份/家族归因 | 只判"行为与声称是否一致"+ 收集欺诈信号 |
| **llm-fingerprint-detector** | ✅ 有参考时精确验证"是不是某模型" | 🟡 可通过距离分档看出"家族亲疏" | 与给定参考做二值比对（match/uncertain/mismatch），不做 open-set 检索 |

### 1.1 LLMmap —— 模型与家族都能识别

- **工作流程**：发 8 条固定指纹查询（identity/probe/越狱等）→ 收集回答 → 用预训练编码器把"查询+回答"编码成 384 维指纹向量 → 与 52 个已知模板做 open-set 距离检索 → 输出 Top-K（距离越小越像）。
- **精确识别**：当被测模型**在 52 个模板库内**时，能精确指认到具体模型名（如 `meta-llama/Meta-Llama-3.1-8B-Instruct`）。
- **家族归因**：当被测模型**不在库内**（如全新模型）时，退化为 open-set 最近邻——输出距离最近的 Top-K，通常落在**同家族 / 同规模**的模型上，即"归族"。本机实测：Qwen3-4B（库外）→ Top-1 = `Qwen/Qwen2.5-3B-Instruct`（Qwen 家族），距离 13.9 vs 次近 50.9，断层明显。
- **想精确识别库外模型**：跑 `add_new_template.py` 入库（无重训，但每模型要 N×8 次完整生成，CPU 上很慢）。入库前只能归族，不能精确指认。
- **本机评估精度**：`python test_model.py ./data/pretrained_models/default -k 3` 可在作者测试集上评估 Top-K 准确率。

### 1.2 LLM Verify —— 不做身份识别，只做欺诈裁决

- **工作流程**：对端点跑 32 条取证探测（identity / capability / fingerprint 三套件）→ 收集回答文本 + 延迟 + token 用量 + 错误 → 多路信号分析（身份一致性 / 知识截止一致性 / 能力边界 / 代理信号 / 相似性）→ 汇总红旗（按严重级排序）→ 裁决。
- **识别粒度**：它**不回答"这模型是谁"**，也**不做家族归因**。它的输出是"这个端点有没有在骗人"：
  - 例如红旗下"自称 gpt-4，而请求的是 Qwen3-4B"——它只能发现"声称与请求不符"，不能告诉你是哪个模型；
  - 它能做的是**交叉比对**：多个声称"不同型号"的端点是否其实是**同一个底层模型**（相似度>阈值判为同一）。
- **裁决等级（fail-closed）**：`FRAUD_DETECTED`(0.0) / `SUSPICIOUS`(0.25) / `INCONCLUSIVE`(0.5) / `NO_FRAUD_SIGNALS`(1.0)。证据不足**绝不判清白**：至少 8 条成功探测且成功率≥80% 才算证据充分。

### 1.3 llm-fingerprint-detector —— 验证"是不是它"，不做开放集识别

- **工作流程**：对端点采样**单 token 输出分布**（随机数字/颜色/字母/动物/抛硬币等 16 个 cell，中英文，`temperature=1.0`、`max_tokens=16`、关隐藏思考）→ 与**参考指纹**逐 cell 算 JSD → 按论文基线尺度给出 match/uncertain/mismatch。
- **识别粒度**：
  - 它不做 open-set 检索，**必须给一个参考指纹**才能下结论（"它是不是参考那个模型"）；
  - 距离本身能体现**家族亲疏**：论文公开基线上，同模型 JSD≈0.14、同模型不同 provider≈0.227、不同模型≈0.463。本机实测：Qwen3-4B vs qwen3-30b（同族）=0.271；Qwen3-4B vs llama=0.682、vs kimi=0.600（异族）。
- **无参考时的"自一致模式"**（evalstone 默认）：采两次互比，看端点**自己稳不稳定**——能暴露"聚合器轮换后端"，但**不能证明身份**。

---

## 2. 支持哪些模型（三件套各自的能力边界）

### 2.1 LLMmap —— 内置 52 个模板（全列表）

模板文件：`LLMmap/data/pretrained_models/default/templates.json`，共 **52 个模型**：

| 家族 | 模型 |
|---|---|
| **Qwen** | Qwen2-1.5B / 7B / 72B-Instruct、Qwen2.5-0.5B / 3B-Instruct |
| **Llama** | Llama-2-7B-chat、Llama-3-8B / 70B-Instruct、Llama-3.1-8B / 70B-Instruct、Llama-3.2-1B / 3B-Instruct、Llama-3-8B-Gradient-1048k、Llama-2-7B-32K |
| **GPT/Claude（API 采样）** | gpt-3.5-turbo、gpt-4-turbo-2024-04-09、gpt-4o-2024-05-13、claude-3-opus/haiku/sonnet |
| **Gemma** | gemma-2b / 7b / 1.1-2b / 1.1-7b / 2-9b / 2-27b |
| **Phi** | Phi-3-mini / medium (4k/128k)、Phi-3.5-mini / MoE |
| **Mistral/Mixtral** | Mistral-7B-Instruct v0.1/v0.2/v0.3、Mixtral-8x7B-v0.1 |
| **其他** | aya-23-8B/35B、zephyr-7b-beta、Nous-Hermes-2-Mixtral、Smaug-Llama-3-70B、granite-3.0/3.1-8b、internlm2_5-7b-chat、Falcon3-7B/10B、Phi-3 系、openchat-3.5/3.6、SOLAR-10.7B、EuroLLM-1.7B 等 |

- **支持新增**：库外模型先用"归族"；要精确识别就 `add_new_template.py <名字> <类型> --num_prompt_confs N` 入库（类型 0=HF / 1=OpenAI / 2=Anthropic）。
- 注意 LLMmap0.2 是 PyTorch 重制版，`add_new_template` 目前主要支持 HF 后端。

### 2.2 LLM Verify —— 无模型库，任意兼容端点

- **没有任何模型库/模板**。只要能连上的 OpenAI / Anthropic / 兼容端点，`model_configs` 里加一行就能测（`provider`：`openai` / `anthropic` / `suspect` / `generic`；`protocol` 自动推断）。
- "支持哪些模型"= **全部**，代价是它不识别身份，只管欺诈信号。
- 想横向对比时，官方建议用免费层拿官方基线：**Gemini**（15 RPM 免费）、**Mistral**（试用额度）、**Groq**、**OpenRouter**（部分模型免费）。

### 2.3 llm-fingerprint-detector —— 11 个内置参考 + 任意模型自采

内置参考（`node dist/cli.js references` 列出，论文公开数据集采样，2026-07-08 采集，15 cells）：

| 内置 reference id（也直接可作 `--detector-reference`） |
|---|
| `mistralai/mistral-small-3.2-24b-instruct` |
| `moonshotai/kimi-k2` |
| `deepseek/deepseek-chat` |
| `meta-llama/llama-3.1-8b-instruct` |
| `qwen/qwen3-30b-a3b-instruct-2507` |
| `openai/gpt-4o` · `openai/gpt-4o-mini` · `openai/gpt-4.1-mini` |
| `google/gemini-2.5-flash` |
| `z-ai/glm-4.5` |
| `anthropic/claude-sonnet-4.5` |

- 之外任意模型：只要用 `fingerprint --out xxx.json` 对可信端点采一份**同协议参考**，立刻就能验证（每模型约 100~400 次单 token 请求）。
- 本机已备同协议参考：`qwen3-4b_reference.json`（Qwen3-4B）、`glm520_reference.json`（GLM-5.2）。
- 注意：这 11 个内置参考用**论文协议**采样，与本机 `one-token/v1` 协议对比**仅指示性**（`protocolMismatch` 标志）。

---

## 3. 线上公开数据 / 别人测过的数据

| 工具 | 公开论文 | 公开数据集 | 在线 Demo / 他人测试数据 |
|---|---|---|---|
| **LLMmap** | ✅ [arXiv:2407.15847](https://arxiv.org/pdf/2407.15847)，**USENIX Security 2025**（Pasquini 等） | 🟡 论文方法公开，作者测试过当时 50+ 模型；本仓库自带 52 模板 + 预训练模型 + 测试集可本地复现（`test_model.py -k 3` 评估 Top-K 精度） | ❌ 无官方在线 Web 工具；仓库内 `results/` 是本机自测数据 |
| **LLM Verify** | 🟡 开源项目 README 附**真实案例演示**（调查 opuscode.pro 等模型转卖站） | ❌ 无公开测试数据集；裁决靠本地跑 32 条探测 + 你的基线端点 | 🟡 无在线服务版；可用免费层 API 自建官方基线 |
| **llm-fingerprint-detector** | ✅ [arXiv:2607.10252](https://arxiv.org/abs/2607.10252)（"One Token Is Enough"，Bruckner） | ✅ **Zenodo 公开数据集**：DOI [10.5281/zenodo.21278557](https://doi.org/10.5281/zenodo.21278557)（CC-BY-4.0，含 11 个模型的单 token 采样数据，即内置参考的来源）；论文代码 DOI 10.5281/zenodo.21278793 | ✅ **在线 Web 版**：[tosea.ai/free-tools/llm-api-fingerprint-checker](https://tosea.ai/free-tools/llm-api-fingerprint-checker)（纯浏览器运行，免费免安装）；**论文公开基线**：同模型 JSD≈0.14 / 同模型异 provider≈0.227 / 不同模型≈0.463 |

> 一句话：想引用"别人测过的数据"——LLMmap 看 USENIX Security 25 论文；detector 有 Zenodo 公开数据集 + 在线网页工具可直接试；LLM Verify 没有公开数据，但自带真实转卖站案例分析。

---

## 4. 前置条件

### 4.1 需要的东西

| 项 | 容器内（推荐，零配置） | 宿主机直接跑 |
|---|---|---|
| 代码仓库 | 镜像内置：`/opt/evalscope` | `/data1/eval/evalstone` |
| 三个工具仓库 | 镜像内置：`/opt/fptools/{LLMmap,llm-verify,llm-fingerprint-detector}` | `/data1/xii/{LLMmap,llm-verify,llm-fingerprint-detector}` |
| LLMmap 解释器 | `LLMMAP_PYTHON=/usr/local/bin/python3`（已烘入） | `/root/miniconda3/envs/llmmap/bin/python`（torch+transformers+e5 缓存） |
| LLM Verify 解释器 | `LLMVERIFY_PYTHON=/usr/local/bin/python3`（已烘入） | `/root/miniconda3/envs/llmverify/bin/python`（fastapi+httpx） |
| detector 运行时 | Node ≥18.17，`DETECTOR_NODE=node`（已烘入） | 任意 Node，仓库已 `npm run build` |
| 参考指纹 | `/opt/fptools/llm-fingerprint-detector/*_reference.json` | 同 schema 的 json |

> 容器镜像：`evalscope-complete-py312-fp:v2`（自包含，load 后零配置）。
> 容器以 **host 网络**运行，因此容器内直接访问 `localhost:30000` / `localhost:30002` 等宿主机端点即可。

### 4.2 进入容器（如果走容器跑法）

```bash
docker run -d --name fp --network host evalscope-complete-py312-fp:v2 bash
docker exec -it fp bash
cd /opt/evalscope
```

---

## 5. 一条命令跑完三个（fingerprint 套件）

```bash
python bash/run.py --suite fingerprint \
  --model <被测端点的模型名> \
  --api-url <OpenAI 兼容端点>/v1
```

示例（容器内，测 CPU 上的 Qwen3-4B 测试端点 :30002）：

```bash
cd /opt/evalscope
python bash/run.py --suite fingerprint \
  --model Qwen3-4B \
  --api-url http://localhost:30002/v1
```

套件 = `llmmap` + `llm_verify` + `llm_fingerprint_detector` 三个依次跑完，
每个跑完自动写报告并刷新 summary（`results/<model>.xlsx/.csv`）。

---

## 6. 单独跑某一个（含各工具独立用法）

### 6.1 llmmap —— 这模型是谁？

**evalstone 集成方式：**

```bash
python bash/run.py --datasets llmmap \
  --model Qwen3-4B --api-url http://localhost:30002/v1
```

- 发送 8 条指纹查询 → 编码回答 → 与 52 模板 open-set 检索 → Top-K。
- `--expected-model`（已知真实身份时）：score 变严格匹配 flag（1.0/0.0）：

```bash
python bash/run.py --datasets llmmap \
  --model GLM-5.2-w4a8-p800-2 --api-url http://localhost:30000/v1 \
  --expected-model GLM-5.2-w4a8-p800-2
```

**工具独立用法**（`/data1/xii/LLMmap`，环境 `llmmap`）：

```bash
cd /data1/xii/LLMmap
PY=/root/miniconda3/envs/llmmap/bin/python

# ① 交互式：人工发查询、粘贴回答
$PY main_interactive.py --inference_model_path ./data/pretrained_models/default

# ② 非交互：回答文件每行一条(8条) → 识别 Top-K
$PY run_identify.py answers.txt -k 6 --device cpu

# ③ 自动：对本地 HF 模型一条龙（发查询→收回答→识别）
$PY run_real_identify.py --model_dir /data1/models/Qwen3-4B \
     --k 6 --device cpu --save_answers qwen_answers.txt

# ④ 入库新模型（精确指认库外模型）
$PY add_new_template.py my-new-model 0 --num_prompt_confs 100

# ⑤ 在作者测试集上评估 Top-K 精度
$PY test_model.py ./data/pretrained_models/default -k 3
```

已知坑：`LLMmap/llm.py` 的 HF 后端强制要求 `HUGGINGFACE_API_KEY`（本地也给假 key）；入库慢（CPU 200 次生成几小时）。

### 6.2 llm_verify —— 这个 API 是不是在骗我？

**evalstone 集成方式：**

```bash
python bash/run.py --datasets llm_verify \
  --model Qwen3-4B --api-url http://localhost:30002/v1
```

- 跑 32 条取证探测 → 红旗 → 裁决。可选 `--protocol`、`--suites`、`--bench-timeout`。

**工具独立用法**（`/data1/xii/llm-verify`，环境 `llmverify`，FastAPI 服务）：

```bash
cd /data1/xii/llm-verify
/root/miniconda3/envs/llmverify/bin/python -m uvicorn src.main:app --host 0.0.0.0 --port 8000
# 或: benchmarker serve --host 0.0.0.0 --port 8000
```

```bash
B=http://localhost:8000

# ① 单套件（identity | capability | fingerprint）
curl -s -X POST $B/api/v1/benchmarks/ -H "Content-Type: application/json" -d '{
  "name": "GLM identity", "prompt_suite": "identity",
  "model_configs": [{"model_name": "GLM-5.2-w4a8-p800-2", "provider": "suspect",
                     "api_key": "dummy", "api_base_url": "http://localhost:30000/v1"}]}'

# ② 深度分析（最常用：三套件全跑 + 红旗 + 裁决）
curl -s -X POST $B/api/v1/analysis/deep -H "Content-Type: application/json" -d '{
  "name": "GLM 全量", "suites": ["identity","capability","fingerprint"],
  "model_configs": [{"model_name": "GLM-5.2-w4a8-p800-2", "provider": "suspect",
                     "api_key": "dummy", "api_base_url": "http://localhost:30000/v1"}]}'

# ③ 探测明细 / 行为指纹
curl -s "$B/api/v1/results/<run_id>"
curl -s "$B/api/v1/results/<run_id>/fingerprint?model_name=GLM-5.2-w4a8-p800-2"

# ④ 两个 run 对比（同一套件下）
curl -s -X POST $B/api/v1/results/compare -H "Content-Type: application/json" \
  -d '{"run_a":"<id>","run_b":"<id>"}'
```

`model_configs` 字段：`model_name` / `provider`(openai|anthropic|suspect|generic) / `api_base_url`(带 `/v1`) / `api_key`(本地可空/dummy) / `protocol`(留空自动推断)。
`api_key` 为空时服务会从 env（`SUSPECT_API_KEY`/`OPENAI_API_KEY`）读；evalstone 集成自动填占位 key。

### 6.3 llm_fingerprint_detector —— 单 token 输出分布验证（重点）

**evalstone 集成方式**（两种模式二选一）：

```bash
# A. 自一致模式（默认）——只证明"端点稳定"，不证明身份
python bash/run.py --datasets llm_fingerprint_detector \
  --model Qwen3-4B --api-url http://localhost:30002/v1

# B. 参考验证模式——验证"是不是它声称的模型"，测身份必须用这个
python bash/run.py --datasets llm_fingerprint_detector \
  --model Qwen3-4B --api-url http://localhost:30002/v1 \
  --detector-reference /data1/xii/llm-fingerprint-detector/qwen3-4b_reference.json \
  --detector-preset strict
```

**工具独立用法**（`/data1/xii/llm-fingerprint-detector`，Node，已 `npm run build`）：

```bash
cd /data1/xii/llm-fingerprint-detector
export LLM_FINGERPRINT_API_KEY=dummy     # 本地端点无鉴权

node dist/cli.js references                                  # ① 列出 11 个内置参考
node dist/cli.js fingerprint --base-url http://localhost:30000/v1 \
  --model GLM-5.2-w4a8-p800-2 --preset standard --out ref.json   # ② 采样指纹
node dist/cli.js verify --base-url http://localhost:30000/v1 \
  --model GLM-5.2-w4a8-p800-2 --preset standard --reference ref.json   # ③ 验证
node dist/cli.js compare a.json b.json --json                 # ④ 离线比较两份指纹
```

- **判定标尺**（meanJSD，base 2）：`match ≤ 0.25 < uncertain ≤ 0.35 < mismatch`；CLI 退出码 `0=match, 2=mismatch, 3=uncertain, 4=insufficient, 1=error`；`score = max(0, 1-meanJSD)`。
- **`--detector-reference` 三类来源**：①本地同协议 json（`qwen3-4b_reference.json` / `glm520_reference.json`）；②内置 id（上表 11 个，如 `deepseek/deepseek-chat`，仅指示性）；③自采（`fingerprint --out my_ref.json`）。
- 选项：`--preset quick(4×15)/standard(8×25)/strict(16×25)`、`--cells`/`--samples`、`--concurrency`、`--timeout`(ms)、`--api-key-env`。
- `data/reference-fingerprints.sample.json` 是多模型合集（`models` 数组），**不能**直接当单模型 reference 用。

---

## 7. 参数速查表（fingerprint 相关）

| 参数 | 默认值 | 说明 |
|---|---|---|
| `--suite fingerprint` | — | 一次跑三个指纹 benchmark |
| `--datasets <名>` | — | 只跑某一个（`llmmap` / `llm_verify` / `llm_fingerprint_detector`） |
| `--model` | `DeepSeek-V4-Flash-Int8` | 被测端点暴露的模型名 |
| `--api-url` | `http://localhost:30000/v1` | OpenAI 兼容端点（必须带 `/v1`） |
| `--tools-root` | env `FP_TOOLS_ROOT`，默认 `/data1/xii` | 三个工具仓库的父目录 |
| `--llmmap-python` | env `LLMMAP_PYTHON` | LLMmap 执行器解释器 |
| `--verify-python` | env `LLMVERIFY_PYTHON` | LLM Verify 执行器解释器 |
| `--detector-node` | env `DETECTOR_NODE`，默认 `node` | detector 的 Node 可执行文件 |
| `--detector-reference` | 无 | 参考指纹 JSON 或内置 id；缺省 = 自一致模式 |
| `--detector-preset` | `standard` | `quick` / `standard` / `strict` |
| `--expected-model` | 无 | 仅 llmmap：已知真实身份，score 变严格匹配 flag |
| `--fingerprint-timeout` | 120 | 单请求超时（秒） |
| `--folder-name` | `--model` | 顶层输出目录名（`output/<folder-name>/...`） |
| `--seed` | 42 | 报告路径里的 seed |

> 指纹探测（三个执行器）始终给请求注入 `chat_template_kwargs.thinking=false` 关闭思考链，
> 与 `run.py --thinking` 无关，无需也无法用该参数控制。

---

## 8. 输出与结果汇总

每个 benchmark 产出与 EvalScope 同构的报告：

```text
output/<folder-name>/<benchmark>/seed_<seed>/reports/<benchmark>.json
```

报告至少含 `score` 和 `num`，另有各自附加字段：

| benchmark | 报告附加字段 |
|---|---|
| llmmap | `score_mode`、`top1`（name+distance）、`topk` |
| llm_verify | `verdict`、`successful_probes`、`avg_latency_ms`、`red_flags[]` |
| llm_fingerprint_detector | `mode`（reference_verify / self_consistency）、`verdict`、`mean_jsd`、`split_half_jsd`、`reference`、`most_divergent[]` |

另外：
- 计时备份：`output/<folder-name>/active_time/<benchmark>__<model>.json`
- 每个 benchmark 跑完，run.py 自动重写汇总 `results/<model>.xlsx` / `.csv`（指纹类归入分类 **"模型安全与指纹"**）。
- 想只做汇总不重跑：`python bash/collect_results.py --output-dir output/Qwen3-4B --model Qwen3-4B`

---

## 9. 实测示例

以下为 Qwen3-4B @ CPU 测试端点 `:30002` 的实测结果，可直接对照：

```
分类             Benchmark                  得分     实测时间(h)  总样本数
模型安全与指纹   llmmap                     0.7690   0.08        8     ← Top-1=Qwen/Qwen2.5-3B-Instruct（家族归因，距离 13.9 vs 次近 50.9）
模型安全与指纹   llm_verify                 0.0      0.06        32    ← FRAUD_DETECTED（自称 gpt-4 + 平均延迟 29.5s 红旗）
模型安全与指纹   llm_fingerprint_detector   0.92     0.07        4     ← 自一致 match, meanJSD≈0.076
```

> 注：llm_verify 的 0.25（仅延迟红旗→SUSPICIOUS）与 0.0（多一条身份红旗→FRAUD_DETECTED）
> 取决于目标端点当时的行为，属正常波动；CPU 端点延迟高导致的延迟红旗是预期现象。
> detector 的 0.92 是自一致结果，**想证明身份请带 `--detector-reference` 重跑**。

---

## 10. 常见坑 / 排障

| 现象 | 原因与处理 |
|---|---|
| detector 报 `unsupported formatVersion undefined`，且路径指向 `package.json` 之类 | `--detector-reference` 传的不是单模型指纹 JSON（传成了目录 / package.json / 多模型合集 `data/reference-fingerprints.sample.json`）。改传单模型同协议 json（含 `formatVersion:1` + `model` + `cells`，如 `qwen3-4b_reference.json`）或内置 reference id。自验：`node dist/cli.js compare <ref> <ref> --json`，合法时 `meanJsd=0, verdict=match` |
| 自一致模式 match 但没法下身份结论 | 正常，自一致只测稳定性。需带 `--detector-reference` 做参考验证 |
| `LLM Verify` 全部探测失败 | api_key 为空时 httpx 会拒绝空 Bearer 头；执行器会自动填占位 key。若仍失败，检查端点的 `/v1` 路径与 `--fingerprint-timeout` 是否过小 |
| llmmap 直接 0 分报错 | 超过一半查询失败时执行器判 0 分并报错（避免用空回答算出假距离）。CPU 端点慢可调大 `--fingerprint-timeout` |
| CPU 端点上 llm_verify 出延迟红旗 | 预期现象（如 29.5s 平均延迟），不是镜像缺陷 |
| `detector CLI not built` | 工具仓库未 `npm run build`；镜像内已构建，宿主机需自行 `cd llm-fingerprint-detector && npm run build` |
| 容器里找不到 tools | 镜像内 `FP_TOOLS_ROOT=/opt/fptools`；宿主机用 `--tools-root /data1/xii`（默认） |
| 全局 `HF_HUB_OFFLINE=1` 导致其他组件异常 | 镜像已把 e5 嵌入模型缓存烘入，llmmap 在进程内部自行离线，不要全局开 HF_HUB_OFFLINE |
| LLMmap 想精确识别库外模型却只"归族" | 需先 `add_new_template.py` 入库（无重训，但很慢）；入库前只能归族 |

---

## 11. 参考

- 实现与坑：`bash/fingerprint/README.md`
- 理论说明 / 框架对比 / 扩展性：`/data1/xii/model_fingerprint_detection.md`
- 集成入口：`bash/run.py`（`ALL_FINGERPRINT` / `SUITES['fingerprint']` / `run_fingerprint_benchmark`）
- 汇总：`bash/collect_results.py`（分类"模型安全与指纹"）
- LLMmap 论文：arXiv:2407.15847（USENIX Security 2025）｜ llm-fingerprint-detector 论文：arXiv:2607.10252 + 公开数据集 DOI 10.5281/zenodo.21278557 + 在线版 tosea.ai/free-tools/llm-api-fingerprint-checker