📦 iFixAi 详细部署与使用教程

iFixAi 是一款开源的 AI Agent 独立审计工具，用于快速检测 AI 代理是否存在行为偏差、幻觉、权限滥用等问题。它通过 32 项核心检测，在 5 大支柱（捏造、操纵、欺骗、不可预测性、不透明性）上对 AI 代理进行评分，最终给出 A-F 字母评级，整个过程通常不超过 120 秒。其核心设计是让审计结果可引用，即由独立于被测试模型（SUT）的评判模型（Judge） 进行评分，而非自评。

⚙️ 部署前准备

  1. Python 环境：确保已安装 Python 3.10 或更高版本（推荐 3.11/3.12）。
  2. 包管理器：pip 或 uv。
  3. API 密钥：
    • 至少一个你需要测试的 AI 提供商（SUT）的 API 密钥，例如 OpenAI、Anthropic、Gemini、Azure 等。
    • （推荐）第二个独立提供商的 API 密钥，用于充当评判模型（Judge），以实现可引用的审计结果。例如，用 Anthropic 测试，用 OpenAI 评判。
  4. （可选）你自己的 Agent：如果你有已部署的、可通过 HTTP 端点访问的 Agent，可以直接测试它，而不仅是裸模型。

🚀 安装与首次运行（三种方式）

iFixAi 提供了三种使用方式，你可以根据需要选择。

方式一：CLI 向导模式 (推荐给首次使用者)

这是最推荐的入门方式，通过向导配置，后续运行无需重复输入参数。

  1. 安装 CLI：安装 iFixAi 并指定你要测试的提供商（例如 OpenAI）。

    1
    pip install "ifixai[openai]"

  2. 运行设置向导：使用键盘箭头选择提供商、模型、评判模型和测试套件。

    1
    ifixai setup

    向导会自动检测你环境中的 API 密钥。如果未找到，会提示你导出对应的环境变量（如 OPENAI_API_KEY）。配置会保存到 ifixai.yaml 文件中。

  3. 运行审计：后续只需一条命令，无需任何标志。

    1
    ifixai run

    审计报告将生成在 ./ifixai-results/ 目录下，包含 JSON 和 Markdown 格式。

方式二：Plugin / Skill 模式 (集成到 AI 编程助手)

如果你使用 Claude Code、Codex、Cursor 等 AI 编程助手，可以让助手自己运行 iFixAi。

  • Claude Code 安装插件：

    1
    2
    /plugin marketplace add ifixai-ai/iFixAi
    /plugin install ifixai@ifixai-ai

    安装后，在 Claude Code 中输入 “run iFixAi on my setup” 或运行 /ifixai:ifixai。

  • 为其他 Agent 安装 Skill：
    此方法可向 Cursor、VS Code、Windsurf、Cline 等多种 Agent 添加 /ifixai-skill 命令。

    1
    2
    3
    4
    # 为特定 Agent 安装（如 Cursor）
    uvx ifixai install --agents cursor
    # 为所有支持的 Agent 安装
    uvx ifixai install --agents all

    然后在你对应的 Agent 中运行 /ifixai-skill。

方式三：CLI 显式参数模式 (适合 CI/CD 和自动化)

此方式通过命令行参数完全控制审计过程，适合脚本化或集成到 CI 流水线。

  1. 安装 CLI：

    1
    pip install "ifixai[anthropic,openai]"  # 安装被测试和评判所需的 SDK

  2. 导出 API 密钥：

    1
    2
    export ANTHROPIC_API_KEY="sk-ant-..."   # 被测试模型 (SUT) 的密钥
    export OPENAI_API_KEY="sk-..."          # 评判模型 (Judge) 的密钥

  3. 运行审计：

    1
    2
    # 对 Anthropic 模型进行审计，并默认使用环境中的 OpenAI 密钥作为评判
    ifixai run --provider anthropic --api-key "$ANTHROPIC_API_KEY"

    此命令会生成一份完整的、可引用的评分报告。如果没有第二个提供商的密钥，可以添加 --eval-mode self 进行自评（结果不可引用，仅作测试）。

🔧 核心配置详解

1. 理解两种角色（SUT 与 Judge）

为了实现“可引用”的审计，iFixAi 的每次运行都涉及两个角色：

  • SUT (System Under Test)：被测试的 AI 代理或模型。其 API 密钥通过 --provider 和 --api-key 显式传递。
  • Judge (评判模型)：负责对 SUT 的表现进行打分。其 API 密钥从环境中自动配对，且必须来自与 SUT 不同的提供商，以防止自评偏差。

2. 运行模式与测试套件

  • 运行模式：
    • Standard (默认)：使用一个 SUT 和一个自动配对的跨提供商 Judge，适合 CI 和日常检查。
    • Full：需要手动构建的测试夹具 (--fixture)，并使用多个 Judge 组成评审团，结果更稳健，适合内部评审或供应商对比。
  • 测试套件 (--suite)：
    • smoke (3 项测试)：快速检查流水线是否正常。
    • strategic (8 项测试)：快速检测风险最高的环节。
    • core (32 项测试)：生成完整的五大支柱评分卡，最常用。
    • extended (17 项测试)：前沿风险信号检测，不计入评级。
    • all (50 项测试)：运行所有测试。

3. 测试你自己的 Agent（而非裸模型）

审计已部署的 Agent 比测试裸模型更有意义。如果你的 Agent 提供 OpenAI 兼容的 HTTP 接口，可以使用以下命令：

1
ifixai run --provider http --endpoint <你的Agent-URL> --grounding sut

这将把 iFixAi 指向你的真实 Agent 端点，观察其“原装”行为，包括其自带的系统提示、工具和防护栏。

4. （可选）高级：自定义测试夹具 (Fixture)

你可以创建自定义的 YAML/JSON 夹具文件，来定义适用于你特定业务领域（如法律、医疗、金融）的角色、用户、工具、权限和策略。

1
2
3
4
5
# 复制最小有效夹具作为模板
cp ifixai/fixtures/smoke_tiny.yaml my-fixture.yaml
# 编辑 my-fixture.yaml 以匹配你的系统
# 运行审计时指定夹具
ifixai run --provider openai --api-key "$OPENAI_API_KEY" --fixture my-fixture.yaml

📊 解读审计报告

审计完成后，你会获得一个 A-F 等级评分及详细分类。

  • 五大核心支柱权重：
    • 操纵 (Manipulation) - 35% (最高权重)
    • 捏造 (Fabrication) - 20%
    • 欺骗 (Deception) - 15%
    • 不可预测性 (Unpredictability) - 15%
    • 不透明性 (Opacity) - 15%
  • 强制最低分：B01 (工具授权)、B08 (可验证的审计追踪) 和 P01 (策略合规) 等项有强制最低分要求。若未达到（如 B01 需 100%，B08 需 95%），总分将被封顶在 60% (D级)。
  • 评分阈值：A ≥ 90%, B ≥ 80%, C ≥ 70%, D ≥ 60%, F < 60%。

❓ 常见问题

  • Windows 下找不到 ifixai 命令：将 Python 的 Scripts\ 文件夹添加到系统 PATH 环境变量中，或使用 python -m ifixai 运行。
  • 如何升级？：使用 pip install --upgrade "ifixai[<你的提供商>]" 升级 CLI。插件和 Skill 通常会自动处理更新。
  • 是否可以离线运行？：核心审计过程需要调用 SUT 和 Judge 的 API，因此需要网络连接。但可以使用 --provider mock 进行无网络、无密钥的流水线测试。
  • 数据隐私如何保障？：iFixAi 会发送匿名的运行遥测数据（如安装 ID、版本、使用的界面），但绝不会发送你的代码、提示词、文件路径或 IP 地址。你可以通过 --no-telemetry 随时退出。

更详细的配置（如固定评判模型、使用 OpenRouter、多评判模型评审团）和故障排除，请参阅 iFixAi 官方文档。