promptfoo/promptfoo-action
GitHub: promptfoo/promptfoo-action
将 promptfoo 集成到 GitHub Actions 的自动化工具，用于在 CI/CD 流程中评估和测试 LLM 提示词、智能体及 RAG 系统的安全性与性能表现。
Stars: 43 | Forks: 15
# LLM Prompt 评估的 Github Action
此 Github Action 使用 [promptfoo](https://www.promptfoo.dev) 来生成编辑提示词的前后对比视图。
当你更改提示词时，评估结果将自动发布到 Pull Request 上：
提供的链接会打开 promptfoo Web 查看器，允许你交互式地探索更改前后的对比：
## 支持的事件
此 Action 支持多种 GitHub 事件类型：
- **Pull Request** (`pull_request`, `pull_request_target`) - 比较 base 和 head 分支之间的变更
- **Push** (`push`) - 比较提交之间的变更 *(需要 v1.1.0+)*
- **手动触发** (`workflow_dispatch`) - 允许使用自定义输入进行手动评估 *(需要 v1.1.0+)*
## 配置
可以使用以下输入参数配置此 Action：
| Parameter | Description | Required |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `config` | 配置文件的路径。此文件包含 Action 的设置。 | Yes |
| `github-token` | Github token。用于验证对 Github API 的请求。 | Yes |
| `cache-path` | 缓存路径。这是 Action 存储临时数据的地方。 | No |
| `no-share` | 禁用评估结果的共享。默认为 `false`（启用共享）。详情请参阅 [共享结果](#sharing-results)。 | No |
| `promptfoo-version` | 要使用的 promptfoo 版本。默认为 `latest` | No |
| `working-directory` | 运行 `promptfoo` 的工作目录。可以设置为已安装 `promptfoo` 的位置。 | No |
| `prompts` | 提示词文件的 glob 模式。这些模式用于查找 Action 应评估的提示词文件。 | No |
| `use-config-prompts` | 使用配置文件中设置的提示词文件。默认为 `false` | No |
| `env-files` | 要加载的 .env 文件的逗号分隔列表（例如 ".env,.env.test.local"）。运行 promptfoo 之前将加载这些文件中的环境变量。 | No |
| `fail-on-threshold` | 如果评估成功率低于此百分比 (0-100)，则 Action 失败。例如：`80` 表示 80% 的成功率。 | No |
| `max-concurrency` | 并发 API 调用的最大数量。默认为 `4`。用于限速。 | No |
| `no-table` | 使用 `--no-table` 标志运行 promptfoo 以保持最小输出。默认为 `false` | No |
| `no-progress-bar` | 使用 `--no-progress-bar` 标志运行 promptfoo 以保持最小输出。默认为 `false` | No |
| `no-cache` | 使用 `--no-cache` 标志运行 promptfoo 以避免读取或写入磁盘缓存。默认为 `false` | No |
| `disable-comment` | 禁止向 PR 发布评论。默认为 `false` | No |
| `force-run` | 即使没有文件更改也强制运行评估。默认为 `false` | No |
支持以下 API key 参数：
| Parameter | Description |
| ----------------------- | ------------------------------------------------------------------------------------ |
| `openai-api-key` | OpenAI 的 API key。用于验证对 OpenAI API 的请求。 |
| `azure-api-key` | Azure OpenAI 的 API key。用于验证对 Azure OpenAI API 的请求。 |
| `anthropic-api-key` | Anthropic 的 API key。用于验证对 Anthropic API 的请求。 |
| `huggingface-api-key` | Hugging Face 的 API key。用于验证对 Hugging Face API 的请求。 |
| `aws-access-key-id` | AWS access key ID。用于验证对 AWS 服务的请求。 |
| `aws-secret-access-key` | AWS secret access key。用于验证对 AWS 服务的请求。 |
| `replicate-api-key` | Replicate 的 API key。用于验证对 Replicate API 的请求。 |
| `palm-api-key` | Palm 的 API key。用于验证对 Palm API 的请求。 |
| `vertex-api-key` | Vertex 的 API key。用于验证对 Vertex AI API 的请求。 |
| `cohere-api-key` | Cohere 的 API key。用于验证对 Cohere API 的请求。 |
| `mistral-api-key` | Mistral 的 API key。用于验证对 Mistral API 的请求。 |
| `groq-api-key` | Groq 的 API key。用于验证对 Groq API 的请求。 |
### 环境变量
所有 workflow 环境变量都会传递给 promptfoo。你可以在 job/workflow 级别设置 API key，而不是作为 Action 输入：
```
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
steps:
- uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
```
Action 输入优先于环境变量。有关输入参数到环境变量的完整映射，请参阅 action.yml。
## 使用示例
### Pull Request 评估
以下是使用 "typpo/promptfoo-action@v1" 并包含缓存步骤的通用 Github Action 配置：
```
name: 'Prompt Evaluation'
on:
pull_request:
paths:
- 'prompts/**'
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read # Required for actions/checkout
pull-requests: write # Ability to post comments on Pull Requests
steps:
# Required for promptfoo-action's git usage
- uses: actions/checkout@v4
# This cache is optional, but you'll save money and time by setting it up!
# IMPORTANT: Use actions/cache@v4 or later (required after Feb 1, 2025)
- name: Set up promptfoo cache
uses: actions/cache@v4
with:
path: |
~/.promptfoo/cache
.promptfoo-cache
key: ${{ runner.os }}-promptfoo-${{ hashFiles('prompts/**') }}-${{ github.sha }}
restore-keys: |
${{ runner.os }}-promptfoo-${{ hashFiles('prompts/**') }}-
${{ runner.os }}-promptfoo-
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
cache-path: '.promptfoo-cache'
```
### 手动触发 (workflow_dispatch)
你也可以使用 workflow_dispatch 手动触发评估：
```
name: 'Prompt Evaluation - Manual'
on:
workflow_dispatch:
inputs:
files:
description: 'Files to evaluate (leave empty to auto-detect)'
required: false
type: string
base:
description: 'Base branch/commit to compare against'
required: false
default: 'HEAD~1'
type: string
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read
actions: write # Required for workflow summaries
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch all history for comparisons
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@main
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
```
手动触发时：
- 如果提供了 `files` 输入，则仅评估这些文件（每行一个文件）
- 如果提供了 `base` 输入，它将与该分支/提交进行比较
- 如果未提供任何输入，它将与上一次提交 (HEAD~1) 进行比较
- 结果将显示在 workflow 摘要中，而不是 PR 评论中
- **重要**：写入 workflow 摘要需要 `actions: write` 权限
#### 替代方案：使用 Action 输入
你也可以直接将 files 和 base 指定为 Action 输入：
```
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@main
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
workflow-files: |
prompts/prompt1.txt
prompts/prompt2.txt
workflow-base: 'main'
```
### Push 事件评估
在每次推送到 main 分支时评估提示词：
```
name: 'Prompt Evaluation - Push'
on:
push:
branches:
- main
paths:
- 'prompts/**'
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read
actions: write # Required for workflow summaries
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 2 # Need at least 2 commits for comparison
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@main
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
```
## 技巧
如果你使用的是 OpenAI 模型，请记住在 Repository Settings > Secrets and Variables > Actions > New repository secret 中创建 secret。
有关如何设置 promptfoo 配置的更多信息，请参阅 [文档](https://promptfoo.dev/docs/getting-started)。
## 使用 .env 文件
如果你的应用程序使用 `.env` 文件存储环境变量，你可以在运行 promptfoo 评估之前加载它们：
```
name: 'Prompt Evaluation'
on:
pull_request:
paths:
- 'prompts/**'
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
env-files: '.env,.env.test.local' # Load multiple .env files
```
这对于 Next.js 应用程序或其他使用 `.env` 文件进行配置的框架特别有用。在评估期间，这些文件中的环境变量将可供 promptfoo 使用。
## 自定义 Provider 检测
此 Action 会自动检测 promptfoo 配置中引用的自定义 provider 文件的更改。当你通过 `file://` URL 使用自定义 provider 时，这些文件的更改将触发评估。
### 支持的模式
1. **直接文件引用：**
providers:
- file://custom_provider.py
- id: file://providers/my_provider.js
2. **通配符模式：**
providers:
- file://providers/*.py # providers/ 中的所有 Python 文件
- file://lib/**/*.js # lib/ 中递归的所有 JS 文件
3. **目录监视：**
providers:
- file://providers/ # 监视整个目录
### 工作原理
- 当你指定通配符模式（例如 `file://providers/*.py`）时，Action 会监视整个目录
- 对任何与模式匹配的文件的更改都会触发评估
- 目录路径会自动监视该目录内的所有文件
- 这适用于 provider、prompts、测试数据文件和断言文件
### 示例配置
```
# promptfooconfig.yaml
providers:
- file://providers/**/*.py # Watch all Python files recursively
prompts:
- file://prompts/ # Watch entire prompts directory
tests:
- vars:
context: file://data/*.json # Watch all JSON files in data/
assert:
- type: javascript
value: file://validators/ # Watch all files in validators/
```
### 强制运行评估
如果你需要无论文件是否更改都运行评估，请使用 `force-run` 选项：
```
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
force-run: true
```
## 缓存以提升性能
promptfoo-action 集成了 GitHub Actions 缓存和 promptfoo 的内部缓存，可显著降低 API 成本和评估时间。
### 为什么缓存很重要
- **成本节约**：避免对 OpenAI、Anthropic 和其他 provider 进行冗余 API 调用
- **速度**：缓存的评估可在几秒钟内完成，而不是几分钟
- **可靠性**：减少对外部 API 可用性的依赖
- **一致性**：确保各次运行的结果可复现
### 工作原理
此 Action 使用多层缓存策略：
1. **promptfoo 内部缓存**：缓存单个 API 响应（默认：CI 中 TTL 为 1 天）
2. **GitHub Actions 缓存**：在 workflow 运行之间持久化缓存
3. **智能失效**：缓存键包含内容哈希，用于自动失效
### 基本设置
```
name: 'Prompt Evaluation with Caching'
on:
pull_request:
paths:
- 'prompts/**'
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v5
with:
fetch-depth: 0 # Required for git diff comparisons
# IMPORTANT: Use actions/cache@v4 or later (required after Feb 1, 2025)
- name: Cache promptfoo evaluations
uses: actions/cache@v4
with:
path: |
~/.promptfoo/cache
.promptfoo-cache
# Cache key includes content hash for automatic invalidation
key: ${{ runner.os }}-promptfoo-${{ hashFiles('prompts/**') }}-${{ github.sha }}
restore-keys: |
${{ runner.os }}-promptfoo-${{ hashFiles('prompts/**') }}-
${{ runner.os }}-promptfoo-
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
config: 'promptfooconfig.yaml'
cache-path: '.promptfoo-cache' # Local cache directory
```
### 具有每周轮换的高级缓存
为了在保持效率的同时获得更好的缓存新鲜度：
```
- name: Get cache rotation key
id: cache-key
run: echo "week=$(date +%Y-W%U)" >> $GITHUB_OUTPUT
- name: Cache with weekly rotation
uses: actions/cache@v4
with:
path: ~/.promptfoo/cache
# Weekly rotation ensures fresh results
key: promptfoo-${{ runner.os }}-${{ hashFiles('prompts/**') }}-${{ steps.cache-key.outputs.week }}
restore-keys: |
promptfoo-${{ runner.os }}-${{ hashFiles('prompts/**') }}-
```
### 用于缓存控制的环境变量
此 Action 会自动为 CI 配置最佳缓存设置：
```
- name: Configure cache environment
run: |
echo "PROMPTFOO_CACHE_ENABLED=true" >> $GITHUB_ENV
echo "PROMPTFOO_CACHE_TYPE=disk" >> $GITHUB_ENV
echo "PROMPTFOO_CACHE_PATH=$HOME/.promptfoo/cache" >> $GITHUB_ENV
echo "PROMPTFOO_CACHE_TTL=86400" >> $GITHUB_ENV # 1 day for CI
echo "PROMPTFOO_CACHE_MAX_SIZE=52428800" >> $GITHUB_ENV # 50MB
```
### 缓存指标和监控
Action 提供缓存统计信息作为输出：
```
- name: Run evaluation
id: eval
uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
cache-path: '.promptfoo-cache'
- name: Display cache metrics
run: |
echo "Cache size: ${{ steps.eval.outputs.cache-size-mb }}MB"
echo "Cache files: ${{ steps.eval.outputs.cache-file-count }}"
```
### 最佳实践
1. **始终使用 actions/cache@v4 或更高版本**（2025 年 2 月 1 日之后必需）
2. **在缓存键中包含内容哈希**以实现自动失效
3. **使用 restore-keys 作为回退**以实现部分缓存命中
4. **设置适当的 TTL** - 开发时较短（1 天），稳定提示词时较长
5. **监控缓存大小**以避免达到 GitHub 的 10GB 限制
6. **为不同的提示词集或环境使用单独的缓存**
### 缓存问题故障排除
如果缓存未按预期工作：
1. **启用调试模式**以查看缓存命中/未命中：
- uses: promptfoo/promptfoo-action@v1
with:
debug: true
2. **检查 Action 输出中的**缓存统计信息
3. **验证缓存路径**在保存和恢复之间是否匹配
4. **根据需要通过 GitHub UI 或 API 手动**清除缓存
有关包含所有缓存功能的完整示例，请参阅 [.github/workflows/example-cached.yml](.github/workflows/example-cached.yml)。
## 共享
默认情况下，结果会在线共享。如果没有 `PROMPTFOO_API_KEY`，则会跳过共享，结果仅显示在日志中。
### 身份验证验证
此 Action 会在运行评估**之前**验证你的 `PROMPTFOO_API_KEY`。这确保了：
- **快速失败**：立即检测到无效凭证，节省 CI 时间
- **清晰的错误消息**：你将确切知道身份验证出了什么问题
- **更好的安全性**：身份验证问题不会被掩埋在冗长的评估日志中
如果身份验证失败，Action 将停止并提供清晰的错误消息以及修复说明。
要启用带身份验证的共享：
```
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
env:
PROMPTFOO_API_KEY: ${{ secrets.PROMPTFOO_API_KEY }}
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
```
从 [https://www.promptfoo.app/welcome](https://www.promptfoo.app/welcome) 获取你的 API key。
要显式禁用共享：
```
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
no-share: true
```
## 最小输出
为了减少 CI 中的控制台输出，请在 Action 配置中设置 `no-table: true` 和 `no-progress-bar: true`。
## 将结果持久化为 Artifacts
此 Action 将评估结果写入工作目录中的 `output.json`。你可以将其作为 GitHub Action artifact 上传，以便在 2 周的可共享 URL 过期后保留结果：
```
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
- name: Upload results
uses: actions/upload-artifact@v4
if: always() # Upload even if evaluation fails
with:
name: promptfoo-results
path: output.json
retention-days: 90
```
Artifacts 保留期长达 90 天，可以从 GitHub Actions UI 或通过 GitHub API 下载。
提供的链接会打开 promptfoo Web 查看器，允许你交互式地探索更改前后的对比：
## 支持的事件
此 Action 支持多种 GitHub 事件类型：
- **Pull Request** (`pull_request`, `pull_request_target`) - 比较 base 和 head 分支之间的变更
- **Push** (`push`) - 比较提交之间的变更 *(需要 v1.1.0+)*
- **手动触发** (`workflow_dispatch`) - 允许使用自定义输入进行手动评估 *(需要 v1.1.0+)*
## 配置
可以使用以下输入参数配置此 Action：
| Parameter | Description | Required |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `config` | 配置文件的路径。此文件包含 Action 的设置。 | Yes |
| `github-token` | Github token。用于验证对 Github API 的请求。 | Yes |
| `cache-path` | 缓存路径。这是 Action 存储临时数据的地方。 | No |
| `no-share` | 禁用评估结果的共享。默认为 `false`（启用共享）。详情请参阅 [共享结果](#sharing-results)。 | No |
| `promptfoo-version` | 要使用的 promptfoo 版本。默认为 `latest` | No |
| `working-directory` | 运行 `promptfoo` 的工作目录。可以设置为已安装 `promptfoo` 的位置。 | No |
| `prompts` | 提示词文件的 glob 模式。这些模式用于查找 Action 应评估的提示词文件。 | No |
| `use-config-prompts` | 使用配置文件中设置的提示词文件。默认为 `false` | No |
| `env-files` | 要加载的 .env 文件的逗号分隔列表（例如 ".env,.env.test.local"）。运行 promptfoo 之前将加载这些文件中的环境变量。 | No |
| `fail-on-threshold` | 如果评估成功率低于此百分比 (0-100)，则 Action 失败。例如：`80` 表示 80% 的成功率。 | No |
| `max-concurrency` | 并发 API 调用的最大数量。默认为 `4`。用于限速。 | No |
| `no-table` | 使用 `--no-table` 标志运行 promptfoo 以保持最小输出。默认为 `false` | No |
| `no-progress-bar` | 使用 `--no-progress-bar` 标志运行 promptfoo 以保持最小输出。默认为 `false` | No |
| `no-cache` | 使用 `--no-cache` 标志运行 promptfoo 以避免读取或写入磁盘缓存。默认为 `false` | No |
| `disable-comment` | 禁止向 PR 发布评论。默认为 `false` | No |
| `force-run` | 即使没有文件更改也强制运行评估。默认为 `false` | No |
支持以下 API key 参数：
| Parameter | Description |
| ----------------------- | ------------------------------------------------------------------------------------ |
| `openai-api-key` | OpenAI 的 API key。用于验证对 OpenAI API 的请求。 |
| `azure-api-key` | Azure OpenAI 的 API key。用于验证对 Azure OpenAI API 的请求。 |
| `anthropic-api-key` | Anthropic 的 API key。用于验证对 Anthropic API 的请求。 |
| `huggingface-api-key` | Hugging Face 的 API key。用于验证对 Hugging Face API 的请求。 |
| `aws-access-key-id` | AWS access key ID。用于验证对 AWS 服务的请求。 |
| `aws-secret-access-key` | AWS secret access key。用于验证对 AWS 服务的请求。 |
| `replicate-api-key` | Replicate 的 API key。用于验证对 Replicate API 的请求。 |
| `palm-api-key` | Palm 的 API key。用于验证对 Palm API 的请求。 |
| `vertex-api-key` | Vertex 的 API key。用于验证对 Vertex AI API 的请求。 |
| `cohere-api-key` | Cohere 的 API key。用于验证对 Cohere API 的请求。 |
| `mistral-api-key` | Mistral 的 API key。用于验证对 Mistral API 的请求。 |
| `groq-api-key` | Groq 的 API key。用于验证对 Groq API 的请求。 |
### 环境变量
所有 workflow 环境变量都会传递给 promptfoo。你可以在 job/workflow 级别设置 API key，而不是作为 Action 输入：
```
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
steps:
- uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
```
Action 输入优先于环境变量。有关输入参数到环境变量的完整映射，请参阅 action.yml。
## 使用示例
### Pull Request 评估
以下是使用 "typpo/promptfoo-action@v1" 并包含缓存步骤的通用 Github Action 配置：
```
name: 'Prompt Evaluation'
on:
pull_request:
paths:
- 'prompts/**'
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read # Required for actions/checkout
pull-requests: write # Ability to post comments on Pull Requests
steps:
# Required for promptfoo-action's git usage
- uses: actions/checkout@v4
# This cache is optional, but you'll save money and time by setting it up!
# IMPORTANT: Use actions/cache@v4 or later (required after Feb 1, 2025)
- name: Set up promptfoo cache
uses: actions/cache@v4
with:
path: |
~/.promptfoo/cache
.promptfoo-cache
key: ${{ runner.os }}-promptfoo-${{ hashFiles('prompts/**') }}-${{ github.sha }}
restore-keys: |
${{ runner.os }}-promptfoo-${{ hashFiles('prompts/**') }}-
${{ runner.os }}-promptfoo-
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
cache-path: '.promptfoo-cache'
```
### 手动触发 (workflow_dispatch)
你也可以使用 workflow_dispatch 手动触发评估：
```
name: 'Prompt Evaluation - Manual'
on:
workflow_dispatch:
inputs:
files:
description: 'Files to evaluate (leave empty to auto-detect)'
required: false
type: string
base:
description: 'Base branch/commit to compare against'
required: false
default: 'HEAD~1'
type: string
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read
actions: write # Required for workflow summaries
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch all history for comparisons
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@main
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
```
手动触发时：
- 如果提供了 `files` 输入，则仅评估这些文件（每行一个文件）
- 如果提供了 `base` 输入，它将与该分支/提交进行比较
- 如果未提供任何输入，它将与上一次提交 (HEAD~1) 进行比较
- 结果将显示在 workflow 摘要中，而不是 PR 评论中
- **重要**：写入 workflow 摘要需要 `actions: write` 权限
#### 替代方案：使用 Action 输入
你也可以直接将 files 和 base 指定为 Action 输入：
```
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@main
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
workflow-files: |
prompts/prompt1.txt
prompts/prompt2.txt
workflow-base: 'main'
```
### Push 事件评估
在每次推送到 main 分支时评估提示词：
```
name: 'Prompt Evaluation - Push'
on:
push:
branches:
- main
paths:
- 'prompts/**'
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read
actions: write # Required for workflow summaries
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 2 # Need at least 2 commits for comparison
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@main
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
```
## 技巧
如果你使用的是 OpenAI 模型，请记住在 Repository Settings > Secrets and Variables > Actions > New repository secret 中创建 secret。
有关如何设置 promptfoo 配置的更多信息，请参阅 [文档](https://promptfoo.dev/docs/getting-started)。
## 使用 .env 文件
如果你的应用程序使用 `.env` 文件存储环境变量，你可以在运行 promptfoo 评估之前加载它们：
```
name: 'Prompt Evaluation'
on:
pull_request:
paths:
- 'prompts/**'
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
env-files: '.env,.env.test.local' # Load multiple .env files
```
这对于 Next.js 应用程序或其他使用 `.env` 文件进行配置的框架特别有用。在评估期间，这些文件中的环境变量将可供 promptfoo 使用。
## 自定义 Provider 检测
此 Action 会自动检测 promptfoo 配置中引用的自定义 provider 文件的更改。当你通过 `file://` URL 使用自定义 provider 时，这些文件的更改将触发评估。
### 支持的模式
1. **直接文件引用：**
providers:
- file://custom_provider.py
- id: file://providers/my_provider.js
2. **通配符模式：**
providers:
- file://providers/*.py # providers/ 中的所有 Python 文件
- file://lib/**/*.js # lib/ 中递归的所有 JS 文件
3. **目录监视：**
providers:
- file://providers/ # 监视整个目录
### 工作原理
- 当你指定通配符模式（例如 `file://providers/*.py`）时，Action 会监视整个目录
- 对任何与模式匹配的文件的更改都会触发评估
- 目录路径会自动监视该目录内的所有文件
- 这适用于 provider、prompts、测试数据文件和断言文件
### 示例配置
```
# promptfooconfig.yaml
providers:
- file://providers/**/*.py # Watch all Python files recursively
prompts:
- file://prompts/ # Watch entire prompts directory
tests:
- vars:
context: file://data/*.json # Watch all JSON files in data/
assert:
- type: javascript
value: file://validators/ # Watch all files in validators/
```
### 强制运行评估
如果你需要无论文件是否更改都运行评估，请使用 `force-run` 选项：
```
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
force-run: true
```
## 缓存以提升性能
promptfoo-action 集成了 GitHub Actions 缓存和 promptfoo 的内部缓存，可显著降低 API 成本和评估时间。
### 为什么缓存很重要
- **成本节约**：避免对 OpenAI、Anthropic 和其他 provider 进行冗余 API 调用
- **速度**：缓存的评估可在几秒钟内完成，而不是几分钟
- **可靠性**：减少对外部 API 可用性的依赖
- **一致性**：确保各次运行的结果可复现
### 工作原理
此 Action 使用多层缓存策略：
1. **promptfoo 内部缓存**：缓存单个 API 响应（默认：CI 中 TTL 为 1 天）
2. **GitHub Actions 缓存**：在 workflow 运行之间持久化缓存
3. **智能失效**：缓存键包含内容哈希，用于自动失效
### 基本设置
```
name: 'Prompt Evaluation with Caching'
on:
pull_request:
paths:
- 'prompts/**'
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v5
with:
fetch-depth: 0 # Required for git diff comparisons
# IMPORTANT: Use actions/cache@v4 or later (required after Feb 1, 2025)
- name: Cache promptfoo evaluations
uses: actions/cache@v4
with:
path: |
~/.promptfoo/cache
.promptfoo-cache
# Cache key includes content hash for automatic invalidation
key: ${{ runner.os }}-promptfoo-${{ hashFiles('prompts/**') }}-${{ github.sha }}
restore-keys: |
${{ runner.os }}-promptfoo-${{ hashFiles('prompts/**') }}-
${{ runner.os }}-promptfoo-
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
config: 'promptfooconfig.yaml'
cache-path: '.promptfoo-cache' # Local cache directory
```
### 具有每周轮换的高级缓存
为了在保持效率的同时获得更好的缓存新鲜度：
```
- name: Get cache rotation key
id: cache-key
run: echo "week=$(date +%Y-W%U)" >> $GITHUB_OUTPUT
- name: Cache with weekly rotation
uses: actions/cache@v4
with:
path: ~/.promptfoo/cache
# Weekly rotation ensures fresh results
key: promptfoo-${{ runner.os }}-${{ hashFiles('prompts/**') }}-${{ steps.cache-key.outputs.week }}
restore-keys: |
promptfoo-${{ runner.os }}-${{ hashFiles('prompts/**') }}-
```
### 用于缓存控制的环境变量
此 Action 会自动为 CI 配置最佳缓存设置：
```
- name: Configure cache environment
run: |
echo "PROMPTFOO_CACHE_ENABLED=true" >> $GITHUB_ENV
echo "PROMPTFOO_CACHE_TYPE=disk" >> $GITHUB_ENV
echo "PROMPTFOO_CACHE_PATH=$HOME/.promptfoo/cache" >> $GITHUB_ENV
echo "PROMPTFOO_CACHE_TTL=86400" >> $GITHUB_ENV # 1 day for CI
echo "PROMPTFOO_CACHE_MAX_SIZE=52428800" >> $GITHUB_ENV # 50MB
```
### 缓存指标和监控
Action 提供缓存统计信息作为输出：
```
- name: Run evaluation
id: eval
uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
cache-path: '.promptfoo-cache'
- name: Display cache metrics
run: |
echo "Cache size: ${{ steps.eval.outputs.cache-size-mb }}MB"
echo "Cache files: ${{ steps.eval.outputs.cache-file-count }}"
```
### 最佳实践
1. **始终使用 actions/cache@v4 或更高版本**（2025 年 2 月 1 日之后必需）
2. **在缓存键中包含内容哈希**以实现自动失效
3. **使用 restore-keys 作为回退**以实现部分缓存命中
4. **设置适当的 TTL** - 开发时较短（1 天），稳定提示词时较长
5. **监控缓存大小**以避免达到 GitHub 的 10GB 限制
6. **为不同的提示词集或环境使用单独的缓存**
### 缓存问题故障排除
如果缓存未按预期工作：
1. **启用调试模式**以查看缓存命中/未命中：
- uses: promptfoo/promptfoo-action@v1
with:
debug: true
2. **检查 Action 输出中的**缓存统计信息
3. **验证缓存路径**在保存和恢复之间是否匹配
4. **根据需要通过 GitHub UI 或 API 手动**清除缓存
有关包含所有缓存功能的完整示例，请参阅 [.github/workflows/example-cached.yml](.github/workflows/example-cached.yml)。
## 共享
默认情况下，结果会在线共享。如果没有 `PROMPTFOO_API_KEY`，则会跳过共享，结果仅显示在日志中。
### 身份验证验证
此 Action 会在运行评估**之前**验证你的 `PROMPTFOO_API_KEY`。这确保了：
- **快速失败**：立即检测到无效凭证，节省 CI 时间
- **清晰的错误消息**：你将确切知道身份验证出了什么问题
- **更好的安全性**：身份验证问题不会被掩埋在冗长的评估日志中
如果身份验证失败，Action 将停止并提供清晰的错误消息以及修复说明。
要启用带身份验证的共享：
```
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
env:
PROMPTFOO_API_KEY: ${{ secrets.PROMPTFOO_API_KEY }}
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
```
从 [https://www.promptfoo.app/welcome](https://www.promptfoo.app/welcome) 获取你的 API key。
要显式禁用共享：
```
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
no-share: true
```
## 最小输出
为了减少 CI 中的控制台输出，请在 Action 配置中设置 `no-table: true` 和 `no-progress-bar: true`。
## 将结果持久化为 Artifacts
此 Action 将评估结果写入工作目录中的 `output.json`。你可以将其作为 GitHub Action artifact 上传，以便在 2 周的可共享 URL 过期后保留结果：
```
jobs:
evaluate:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
config: 'promptfooconfig.yaml'
- name: Upload results
uses: actions/upload-artifact@v4
if: always() # Upload even if evaluation fails
with:
name: promptfoo-results
path: output.json
retention-days: 90
```
Artifacts 保留期长达 90 天，可以从 GitHub Actions UI 或通过 GitHub API 下载。标签：Agent, AI红队, CI/CD安全, Claude, CVE检测, DevSecOps, DLL 劫持, Gemini, GitHub Action, GPT, Llama, LLM, MITM代理, Petitpotam, Promptfoo, PR自动评论, RAG, Unmanaged PE, Web Viewer, 上游代理, 大语言模型, 威胁情报, 安全测试, 开发者工具, 开源, 开源框架, 性能对比, 持续集成, 提示词工程, 攻击性安全, 检索增强生成, 模型评估, 漏洞管理, 策略决策点, 自动化攻击, 自动化攻击