promptfoo/promptfoo-action

이 GitHub Action은 모니터링된 파일이 변경될 때 Promptfoo를 사용하여 프롬프트를 평가합니다.

풀 리퀘스트(pull requests)의 경우, 이 액션은 현재 체크아웃을 평가하고 통과/실패 횟수를 요약 댓글로 게시하며, 공유가 활성화된 경우 Promptfoo 웹 뷰어 링크를 함께 제공합니다:

웹 뷰어를 통해 평가 결과를 검사할 수 있습니다:

이 액션은 여러 GitHub 이벤트 유형을 지원합니다:

풀 리퀘스트(Pull Request)(pull_request, pull_request_target) - 풀 리퀘스트 파일 목록을 사용하여 일치하는 프롬프트 파일을 선택하고 PR 댓글을 게시합니다.푸시(Push)(push) - before/after 커밋 SHA를 사용하여 일치하는 프롬프트 파일을 선택하고 워크플로우 요약을 작성합니다.수동 트리거(Manual Trigger)(workflow_dispatch) - 제공된 파일 목록 또는 기본 참조(base ref)와의 git 비교를 사용하여 일치하는 프롬프트 파일을 선택하고 워크플로우 요약을 작성합니다.

변경 감지(change detection)가 불가능한 경우, 이 액션은 구성된 prompts glob에 일치하는 모든 파일을 평가합니다. 이 액션은 현재 체크아웃만 평가하며, 별도의 기본(base) 및 헤드(head) 평가를 실행하지 않습니다.

pull_request_target의 경우, 체크아웃 설정과 자격 증명(credentials) 사용에 각별히 주의해야 합니다. 신뢰할 수 없는 풀 리퀘스트 코드를 권한이 있는 토큰으로 실행하지 마십시오.

이 액션은 다음 입력들을 사용하여 구성할 수 있습니다:

workflow 레벨의 base를 우선하며, 기본값은 HEAD~1입니다. | 아니요 | repeat | 각 테스트가 실행되는 횟수입니다. 최소 2여야 하며, 생략하면 한 번만 실행됩니다. | 아니요 | repeat-min-pass | 각 반복 테스트에 필요한 최소 패스 수입니다. repeat를 필요로 하며 이를 초과할 수 없습니다. | 아니요 | force-run | 변경 감지(change detection)가 관련 파일을 찾지 못하더라도 평가합니다. 기본값은 false입니다. | 아니요 | debug | 호환성을 위해 허용되었지만, 러너 로그 가시성(runner log visibility)을 변경하지는 않습니다. core.debug 메시지를 표시하려면 GitHub Actions 단계 디버그 로깅을 사용하십시오.

다음 API 키 매개변수들이 지원됩니다:

모든 워크플로우 환경 변수는 promptfoo로 전달됩니다. 액션 입력(action inputs)을 사용하는 대신 job 또는 workflow 레벨에서 API 키를 설정할 수 있습니다.

환경 변수(env):
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
steps:
...

Action inputs는 해당 환경 변수보다 우선합니다.
전체 입력 메타데이터는 action.yml을 참조하세요.

변경 프롬프트 필터링(changed-prompt filtering)과 선택적 GitHub Actions 캐시가 적용된 풀 리퀘스트 워크플로우는 다음과 같습니다:

name: 'Prompt Evaluation'
on:
pull_request:
...

또한 workflow_dispatch를 사용하여 수동으로 평가를 트리거할 수도 있습니다:

name: 'Prompt Evaluation - Manual'
on:
workflow_dispatch:
...

수동으로 트리거된 경우:

• files가 제공되면, 해당 경로들이 변경 파일 세트(changed-file set)로 간주됩니다.
• prompts와 일치하는 변경 파일만 --prompts를 통해 전달됩니다.
• base가 제공되면, 액션은 해당 참조(ref)와 HEAD를 비교합니다.
• 입력이 둘 다 제공되지 않으면, 액션은 HEAD~1과 HEAD를 비교합니다.
• 결과는 PR 댓글 대신 워크플로우 요약(workflow summary)에 표시됩니다.

단계 요약(step summary)을 작성하는 데 actions: write가 필요하지 않습니다.

파일 및 base를 액션 입력으로 직접 지정할 수도 있습니다:

- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
...

메인 브랜치(main branch)에 푸시될 때마다 프롬프트를 평가하려면:

name: 'Prompt Evaluation - Push'
on:
push:
...

OpenAI 모델을 사용하는 경우, Repository Settings > Secrets and Variables > Actions > New repository secret에서 시크릿(secret)을 생성하는 것을 잊지 마세요.
promptfoo 설정을 설정하는 방법에 대한 자세한 정보는 문서를 참조하세요.

애플리케이션이 환경 변수 저장을 위해 .env 파일을 사용하는 경우, promptfoo 평가를 실행하기 전에 해당 파일들을 로드할 수 있습니다:

name: 'Prompt Evaluation'
on:
pull_request:
...

이는 Next.js 애플리케이션이나 설정(configuration)을 위해 .env 파일을 사용하는 다른 프레임워크에 특히 유용합니다. 이 파일들로부터 가져온 환경 변수들은 평가 중에 promptfoo에서 사용할 수 있게 됩니다.

prompts가

구성된 경우, action은 또한 Promptfoo 설정에서 참조하는 파일 종속성(file dependencies)을 평가 건너뛰기 여부를 결정하기 전에 확인합니다. 여기에는 사용자 정의 제공자(custom providers), 프롬프트 파일(prompt files), 테스트 변수(test variables), 그리고 단언 파일(assertion files)이 포함됩니다.

워크플로우가 on.<event>.paths 필터를 사용하는 경우, 이러한 종속성 경로도 여기에 포함해야 합니다. action이 변경된 파일을 검사하려면 GitHub가 먼저 워크플로우를 시작해야 합니다.

직접 파일 참조:
providers:

• file://custom_provider.py

• id: file://providers/my_provider.js

와일드카드 패턴:
providers:

• file://providers/*.py # providers 디렉토리의 모든 Python 파일

• file://lib/**/*.js # lib 디렉토리 내 모든 JS 파일을 재귀적으로 검색

• 직접 파일 종속성은 GitHub의 변경된 파일 목록과 비교됩니다.

• 와일드카드 종속성의 경우, action은 기존 일치 항목을 확장하고 또한 비(non-)와일드카드 디렉토리 접두사도 보수적으로 감시합니다.

• 디렉토리 종속성은 해당 디렉토리 아래의 모든 변경된 파일을 감시합니다.

• prompts가 설정되어 있고 action이 평가를 안전하게 건너뛸 수 있는지 결정할 때 종속성 감지(Dependency detection)가 중요합니다. prompts가 없으면, 설정은 지원되는 모든 이벤트에서 평가됩니다.

# promptfooconfig.yaml
providers:
- file://providers/**/*.py # 모든 Python 파일을 재귀적으로 감시
...

파일 변경 여부와 관계없이 평가를 실행하려면 force-run 옵션을 사용하세요:

- name: Run promptfoo evaluation
uses: promptfoo/promptfoo-action@v1
with:
...

LLM 평가 결과는 비결정적(non-deterministic)입니다. 각 테스트를 여러 번 실행하려면 repeat을 사용하고, 테스트당 최소 통과 횟수를 요구하려면 repeat-min-pass를 사용하세요:

- name: Run skill evals
uses: promptfoo/promptfoo-action@v1
with:
...

이 코드는 각 테스트를 3번 실행하고, 각 테스트가 3회 중 최소 2회 통과하도록 요구합니다. 일관되게 실패하는 테스트는 플래그 지정되고, 무작위 채점기(grader) 편차는 허용됩니다.

이를 fail-on-threshold와 결합하여 스위트 수준 검사(suite-level check)를 수행할 수 있습니다. 구성된 모든 검사가 통과해야 합니다.

참고: repeat 검사는 해결된 테스트 케이스, 프롬프트 및 제공업체별로 결과를 그룹화합니다. 의도적으로 정확히 중복되는 테스트를 정의하는 경우, 보고서가 이를 명확하게 구분할 수 있도록 고유한 id 또는 description 값을 부여해야 합니다.**

이 액션은 Promptfoo의 디스크 캐시를 구성합니다. 디스크 내용은 워크플로우에서 actions/cache도 사용하지 않는 한 새로 시작하는 GitHub 호스팅 러너 간에는 유지되지 않습니다.

비용 절감: OpenAI, Anthropic 및 기타 제공업체에 대한 중복 API 호출을 방지합니다.
속도: 캐시된 평가는 훨씬 더 빠르게 완료될 수 있습니다.
신뢰성: 외부 모델 제공업체에 대한 반복적인 호출을 줄입니다.

이 액션은 다음 기능을 수행합니다:

• Promptfoo의 디스크 캐시를 활성화하고 그 경로와 TTL(Time To Live)을 구성합니다.
• 평가 전후의 캐시 크기 및 파일 개수 메트릭을 기록합니다.
• CI=true일 때 7일보다 오래된 캐시 항목을 제거합니다.
• 캐시 디렉터리에 .cache-manifest.json 파일을 작성합니다.

사용자의 워크플로우는 actions/cache 키를 선택하고 작업을 거쳐 디렉터리를 지속적으로 유지할 책임이 있습니다.

name: 'Prompt Evaluation with Caching'
on:
pull_request:
...

효율성을 유지하면서 더 나은 캐시 신선도를 위해:

- name: Get cache rotation key
id: cache-key
run: echo