promptfoo安装和demo使用

Promptfoo Hello World 快速入门指南

什么是 Promptfoo

Promptfoo 是一个强大的 LLM（大型语言模型）评测工具，可以帮助你：

对比不同 prompt 的效果
自动测试 prompt 质量
支持多种 LLM 提供商（OpenAI、Anthropic、自定义 API 等）

环境要求

Node.js 18+
npm 或 yarn

安装步骤

1. 创建项目目录

bash 复制代码

mkdir promptfoo-demo && cd promptfoo-demo
npm init -y

2. 安装 promptfoo

bash 复制代码

npm install promptfoo --save-dev

提示: 如果使用私有 npm 仓库，确保仓库中已同步 promptfoo 包。

3. 验证安装

bash 复制代码

npx promptfoo --version

Hello World 搭建

1. 创建配置文件

在项目根目录创建 promptfooconfig.yaml：

yaml 复制代码

prompts:
  - id: prompt_v1
    label: Prompt v1 (简洁版)
    raw: "{{input}}"

  - id: prompt_v2
    label: Prompt v2 (详细版)
    raw: |
      You are a helpful AI assistant. Please respond to the following request:
      {{input}}
      Follow the instructions above and provide a helpful response.

providers:
  # 使用 Python 自定义 Provider
  - id: python:./providers/custom_llm.py
    label: Custom LLM

tests:
  - name: greeting
    description: 测试问候功能
    providers:
      - python:./providers/custom_llm.py
    prompts:
      - prompt_v1
      - prompt_v2
    vars:
      input: Say hello to someone named Alice
    assert:
      - type: icontains
        value: hello
      - type: icontains
        value: alice

output:
  - type: table
    filename: results/table.html
  - type: json
    filename: results/output.json

2. 创建 Python 自定义 Provider

创建 providers/custom_llm.py：

python 复制代码

"""
自定义 LLM Provider 示例
对接公司内部 LLM 服务
"""
import os
import requests

# 设置 NO_PROXY 避免代理问题
os.environ["NO_PROXY"] = "内部服务地址"
os.environ["no_proxy"] = "内部服务地址"

def call_api(prompt, options=None, context=None):
    """
    promptfoo Python Provider 入口函数

    Args:
        prompt: 渲染后的完整 prompt
        options: promptfoo 选项（如 temperature 等）
        context: 包含 vars 等的上下文

    Returns:
        包含 output 字段的字典
    """
    # 从环境变量或配置获取 LLM 服务地址
    endpoint = os.environ.get("LLM_ENDPOINT", "http://your-llm-service")
    timeout = int(os.environ.get("LLM_TIMEOUT", "300"))
    api_key = os.environ.get("LLM_API_KEY", "")

    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }

    request_body = {
        "user": "promptfoo-user",
        "query": prompt,
        "response_mode": "blocking"
    }

    response = requests.post(
        endpoint,
        headers=headers,
        json=request_body,
        timeout=timeout
    )
    response.raise_for_status()

    # 返回包含 output 字段的字典（promptfoo 要求格式）
    return {"output": response.json().get("answer", "")}

3. 创建目录结构

bash 复制代码

mkdir -p providers results

4. 运行评测

bash 复制代码

npx promptfoo eval

5. 查看结果

bash 复制代码

npx promptfoo view

核心概念

Provider（提供商）

对接 LLM 服务的接口，可以是：

OpenAI、Anthropic 等云服务
本地模型
自定义 API（Python/JS 实现）

Prompt（提示词模板）

定义输入给 LLM 的模板，使用 {``{变量名}} 语法注入变量。

Tests（测试用例）

定义具体的测试场景，包含：

vars: 变量值
assert: 断言规则

断言类型

类型	说明
`contains`	包含指定文本（大小写敏感）
`icontains`	包含指定文本（大小写不敏感）
`equals`	完全相等
`containsAny`	包含任一关键词
`regex`	正则匹配

常见问题

1. Python Provider 加载失败

问题 : Cannot load module from xxx

解决: 确保配置使用文件路径：

yaml 复制代码

- id: python:./providers/custom_llm.py  # 使用相对路径

2. 返回格式错误

问题 : Cannot use 'in' operator to search for 'output'

解决 : Provider 必须返回包含 output 字段的字典：

python 复制代码

return {"output": "生成的文本"}

3. 断言匹配失败

问题: 测试状态为 FAIL

解决:

使用 icontains 替代 contains（大小写不敏感）
检查断言的 value 是否与 LLM 输出匹配
注意 prompt 中的变量是否正确渲染

4. 内网访问 403 错误

问题: 访问内网服务时被代理拦截

解决: 在 Python 代码中设置 NO_PROXY：

python 复制代码

os.environ["NO_PROXY"] = "内部服务地址"
os.environ["no_proxy"] = "内部服务地址"

完整项目结构

复制代码

promptfoo-demo/
├── promptfooconfig.yaml    # 主配置文件
├── providers/
│   └── custom_llm.py       # 自定义 Provider
├── results/                # 测试结果输出目录
└── node_modules/

下一步

添加更多测试用例
尝试不同的断言规则
对比多个 prompt 版本的效果
集成 CI/CD 自动化测试

祝你在 Prompt Engineering 的道路上越走越远！