命令行

promptfoo 命令行工具支持以下子命令：

• init [directory] - 使用虚拟文件初始化一个新项目。
• eval - 评估提示和模型。这是你最常使用的命令！
• view - 启动浏览器 UI 以可视化结果。
• share - 创建一个可以在线分享的 URL。
• cache - 管理缓存。
  • cache clear
• list - 列出各种资源，如评估、提示和数据集。
  • list evals
  • list prompts
  • list datasets
• show <id> - 显示特定资源的详细信息（评估、提示、数据集）。
• delete <id> - 根据 ID 删除资源（目前仅支持评估）
• feedback <message> - 向 Promptfoo 开发者发送反馈。

promptfoo eval

默认情况下，eval 命令将读取当前目录中的 promptfooconfig.yaml 配置文件。但是，如果你想覆盖某些参数，可以提供可选参数：

选项	描述
-a, --assertions <path>	断言文件的路径
-c, --config <paths...>	配置文件的路径。自动加载 promptfooconfig.js/json/yaml
--delay <number>	每次测试之间的延迟（以毫秒为单位）
--description <description>	评估运行的描述
--env-file, --env-path <path>	.env 文件的路径
--filter-failing <path>	包含失败测试的 JSON 输出文件的路径
-n, --filter-first-n <number>	仅运行前 N 个测试
--filter-pattern <pattern>	仅运行描述匹配正则表达式的测试
--filter-providers <providers>	仅使用这些提供者运行测试
--filter-targets <targets>	仅使用这些目标运行测试
--grader <provider>	将用于评分输出的模型
-j, --max-concurrency <number>	并发 API 调用的最大数量
--model-outputs <path>	包含 LLM 输出字符串列表的 JSON 文件的路径
--no-cache	不读取或写入磁盘缓存
--no-progress-bar	不显示进度条
--no-table	不在 CLI 中输出表格
--no-write	不将结果写入 promptfoo 目录
-o, --output <paths...>	输出文件的路径（csv, txt, json, yaml, yml, html）
-p, --prompts <paths...>	提示文件的路径（.txt）
--prompt-prefix <path>	附加到每个提示的前缀
--prompt-suffix <path>	附加到每个提示的后缀
-r, --providers <name or path...>	提供者名称或自定义 API 调用模块的路径
--remote	尽可能强制远程推理（用于红队）
--repeat <number>	每个测试运行的次数
--share	创建可分享的 URL
--suggest-prompts <number>	生成 N 个新提示并将其附加到提示列表
--table	在 CLI 中输出表格
--table-cell-max-length <number>	将控制台表格单元格截断为此长度
-t, --tests <path>	包含测试用例的 CSV 文件的路径
--var <key=value>	以 key=value 格式设置变量
-v, --vars <path>	测试用例的CSV路径（--tests的别名）
--verbose	显示调试日志
-w, --watch	监视配置文件的变化并重新运行

eval 命令在至少有一个测试用例失败时会返回退出代码 100。对于其他错误，它会返回退出代码 1。失败的测试的退出代码可以通过环境变量 PROMPTFOO_FAILED_TEST_EXIT_CODE 覆盖。

promptfoo init [directory]

使用示例文件初始化一个新项目。

选项	描述
directory	创建文件的目录
--no-interactive	不以交互模式运行

promptfoo view

启动一个用于结果可视化的浏览器UI。

选项	描述
-p, --port <number>	本地服务器的端口号
-y, --yes	跳过确认并自动打开URL

如果你使用 PROMPTFOO_CONFIG_DIR 覆盖了 promptfoo 输出目录，请运行 promptfoo view [directory]。

promptfoo share

创建一个可以在线分享的URL。

选项	描述
-y, --yes	在创建可分享URL之前跳过确认

promptfoo cache

管理缓存。

选项	描述
clear	清除缓存

promptfoo feedback <message>

向 promptfoo 开发者发送反馈。

选项	描述
message	反馈信息

promptfoo list

列出各种资源，如评估、提示和数据集。

子命令	描述
evals	列出评估
prompts	列出提示
datasets	列出数据集

选项	描述
-n	显示按创建日期降序排列的前n条记录

promptfoo show <id>

显示特定资源的详细信息。

选项	描述
eval <id>	显示特定评估的详细信息
prompt <id>	显示特定提示的详细信息
dataset <id>	显示特定数据集的详细信息

promptfoo delete <id>

删除特定资源。

选项	描述
eval <id>	按ID删除评估

promptfoo import <filepath>

从JSON格式导入评估文件。

promptfoo export <evalId>

将评估记录导出为JSON格式。要导出最新的记录，请使用 evalId latest。

选项	描述
-o, --output <filepath>	要写入的文件。默认写入标准输出。

环境变量

支持以下通用环境变量：

名称	描述	默认值
PROMPTFOO_ASSERTIONS_MAX_CONCURRENCY	一次运行多少个断言	3
PROMPTFOO_CONFIG_DIR	存储评估历史的目录	~/.promptfoo
PROMPTFOO_DISABLE_AJV_STRICT_MODE	如果设置，禁用AJV严格模式进行JSON模式验证
PROMPTFOO_DISABLE_CONVERSATION_VAR	防止设置 _conversation 变量
PROMPTFOO_DISABLE_JSON_AUTOESCAPE	如果设置，禁用JSON提示中的智能变量替换
PROMPTFOO_DISABLE_REF_PARSER	防止 JSON 模式解引用
PROMPTFOO_DISABLE_TEMPLATING	禁用 Nunjucks 渲染
PROMPTFOO_DISABLE_VAR_EXPANSION	防止数组类型变量被扩展为多个测试用例
PROMPTFOO_FAILED_TEST_EXIT_CODE	当至少有一个测试用例失败或通过率低于 PROMPTFOO_PASS_RATE_THRESHOLD 时，覆盖退出代码	100
PROMPTFOO_PASS_RATE_THRESHOLD	设置最小通过率阈值（以百分比表示）。如果未设置，默认值为 0 次失败	0
PROMPTFOO_REQUIRE_JSON_PROMPTS	默认情况下，聊天完成提供程序会将非 JSON 消息包装在单个用户消息中。将此环境变量设置为 true 可禁用该行为。
FORCE_COLOR	设置为 0 以禁用终端颜色用于打印输出

tip

promptfoo 将从当前工作目录的 .env 中加载环境变量。

promptfoo generate dataset

BETA: 基于现有提示和变量生成合成测试用例。

选项	描述	默认值
-c, --config <path>	配置文件的路径	promptfooconfig.yaml
-w, --write	直接将生成的测试用例写入配置文件	false
-i, --instructions <text>	测试用例生成的自定义指令
-o, --output <path>	写入生成的测试用例的路径	stdout
--numPersonas <number>	要生成的人物角色数量	5
--numTestCasesPerPersona <number>	每个人物角色的测试用例数量	3

例如，此命令将使用新测试用例修改默认配置文件（通常是 promptfooconfig.yaml）：

promptfoo generate dataset -w

此命令将为特定配置生成测试用例并将其写入文件，同时遵循特殊指令：

promptfoo generate dataset -c my_config.yaml -o new_tests.yaml -i '所有针对 {{location}} 的测试用例必须是欧洲城市'

promptfoo redteam init

初始化一个红队项目。

选项	描述	默认值
[directory]	初始化项目的目录	.

示例：

promptfoo redteam init my_project

danger

对抗性测试会产生冒犯性、有毒和有害的测试输入，并可能导致您的系统产生有害输出。

更多详情，请参阅 红队配置。

promptfoo redteam run

运行完整的红队流程（初始化、生成和评估）。

选项	描述	默认值
-c, --config [path]	配置文件的路径	promptfooconfig.yaml
-o, --output [path]	生成测试的输出文件路径	redteam.yaml
--no-cache	不读取或写入磁盘缓存	false
--env-file, --env-path <path>	.env 文件的路径
-j, --max-concurrency <number>	最大并发 API 调用数量
--delay <number>	API 调用之间的延迟（以毫秒为单位）
--remote	尽可能强制远程推理	false
--force	即使未检测到更改也强制生成	false

示例：

promptfoo redteam run -c custom_config.yaml -o custom_output.yaml

promptfoo redteam generate

生成对抗性测试用例以挑战您的提示和模型。

选项	描述	默认值
-c, --config <path>	配置文件路径	promptfooconfig.yaml
-o, --output <path>	生成的测试用例写入路径	redteam.yaml
-w, --write	直接将生成的测试用例写入配置文件	false
--purpose <purpose>	系统用途的高级描述	从配置中推断
--provider <provider>	用于生成对抗性测试的提供者
--injectVar <varname>	覆盖提示中代表用户输入的 {{variable}}	prompt
--plugins <plugins>	要使用的插件列表，逗号分隔	default
--strategies <strategies>	要使用的策略列表，逗号分隔	default
-n, --num-tests <number>	每个插件生成的测试用例数量
--language <language>	生成的测试用例的语言	English
--no-cache	不读取或写入磁盘缓存	false
--env-file, --env-path <path>	.env 文件路径
-j, --max-concurrency <number>	最大并发 API 调用数
--delay <number>	插件 API 调用之间的延迟（毫秒）
--remote	尽可能强制远程推理	false
--force	即使未检测到更改也强制生成	false

例如，假设我们有以下 promptfooconfig.yaml：

prompts:
  - 'Act as a trip planner and help the user plan their trip'

providers:
  - openai:gpt-4o-mini
  - openai:gpt-4o

此命令将生成对抗性测试用例并将其写入 redteam.yaml。

promptfoo redteam generate

此命令覆盖系统用途并注入对抗性用户输入的变量：

promptfoo redteam generate --purpose 'Travel agent that helps users plan trips' --injectVar 'message'

promptfoo redteam eval

与 promptfoo eval 功能相同，但默认加载 redteam.yaml。

promptfoo redteam report

启动浏览器 UI 并打开红队测试报告。

选项	描述	默认值
[directory]	包含红队测试配置的目录	.
-p, --port <number>	服务器端口号	15500
--filter-description <pattern>	使用正则表达式模式过滤评估描述
--env-file, --env-path <path>	.env 文件路径

示例：

promptfoo redteam report -p 8080

仅限 ASCII 输出

要禁用终端颜色输出，请设置 FORCE_COLOR=0（这是由 chalk 库支持的）。

对于 eval 命令，您可能还想禁用进度条和表格，因为它们使用特殊字符：

FORCE_COLOR=0 promptfoo eval --no-progress-bar --no-table