Skip to main content

为 promptfoo 贡献

我们欢迎社区的贡献，帮助改进 promptfoo。本指南将帮助你入门。如有任何问题，请通过 Discord 或 GitHub 问题 联系我们。

项目概述​

promptfoo 是一个 MIT 许可的工具，用于测试和评估 LLM 应用程序。

我们特别欢迎在以下领域的贡献：

  • 错误修复
  • 文档更新，包括示例和指南
  • 提供者更新，包括新模型、新功能（工具使用、函数调用、JSON 模式、文件上传等）
  • 改进 promptfoo 用户体验的功能，特别是与 RAG、代理和合成数据生成相关的功能。

入门指南​

  1. 在 GitHub 上 fork 仓库。

  2. 在本地克隆你的 fork：

    git clone https://github.com/[你的用户名]/promptfoo.git
    cd promptfoo

  3. 设置开发环境：

    3.1. 本地设置

    # 我们推荐使用 .nvmrc 文件中指定的 Node.js 版本（确保 node >= 18）
    nvm use
    npm install

    3.2 使用 devcontainer 设置（需要 Docker 和 VSCode）

    在 VSCode 中打开仓库，点击“在容器中重新打开”按钮。这将构建一个包含所有必要依赖项的 Docker 容器。

    现在安装基于 node 的依赖项：

    npm install

  4. 运行测试以确保一切正常：

    npm test

  5. 构建项目：

    npm run build

  6. 运行项目：

    npm run dev

    这将在端口 15500 上运行 express 服务器，在端口 3000 上运行 Web UI。 当你进行更改时，API 和 UI 都会自动重新加载。

    注意：开发体验与生产环境中的运行方式略有不同。在开发中，Web UI 使用 Vite 服务器提供服务。在所有其他环境中，前端是构建并通过 Express 服务器作为静态站点提供的。

如果你不确定从哪里开始，请查看我们的 good first issues 或加入我们的 Discord 社区 获取指导。

开发工作流程​

  1. 为你的功能或错误修复创建一个新分支：

    git checkout -b feature/你的功能名称

  2. 我们尝试遵循 Conventional Commits 规范。这对于功能分支不是必需的。我们将所有 PR 合并到 main 分支，并使用 squash merge 和常规提交消息。

  3. 将你的分支推送到你的 fork：

    git push origin 你的分支名称

  4. 针对 promptfoo 仓库的 main 分支打开一个拉取请求。

当打开拉取请求时：

  • 保持更改小而专注。避免将重构与新功能混合。
  • 确保新代码或错误修复的测试覆盖率。
  • 提供清晰的说明，说明如何重现问题或测试新功能。
  • 对反馈做出响应，并准备好根据请求进行更改。
  • 确保你的测试通过，并且你的代码正确地进行了 lint。

不要犹豫，寻求帮助。我们在这里支持你。如果你担心你的 PR 是否会被接受，请先与我们交谈（参见 获取帮助）。

测试​

运行测试​

我们使用 Jest 进行测试。要运行测试套件：

npm test

要运行测试的监视模式：

npm run test:watch

你也可以使用以下命令运行特定测试：

npx jest [模式]

编写测试​

编写测试时，请：

  • 使用 --randomize 标志运行测试，以确保你的 mock 设置和拆卸不会影响其他测试。
  • 检查覆盖率报告，确保你的更改被覆盖。
  • 避免向控制台添加额外的日志。

Linting 和格式化​

我们使用 ESLint 和 Prettier 进行代码 linting 和格式化。在提交拉取请求之前，请运行：

npm run format
npm run lint

建议运行 npm run lint -- --fix 命令来自动修复一些 linting 错误。

构建项目​

要构建项目：

npm run build

在开发期间持续构建 API：

npm run build:watch

为 CLI 贡献​

在开发期间运行 CLI​

我们推荐使用 npm link 将本地的 promptfoo 包链接到全局的 promptfoo 包：

npm link
promptfoo --help

我们建议在开发 CLI 时，在单独的终端中运行 npm run build:watch。这将自动在你进行更改时构建 CLI。

或者，你可以直接运行 CLI：

npm run local -- eval --config examples/cloudflare-ai/chat_config.yaml

在开发新功能时，我们建议设置一个本地的 promptfooconfig.yaml 来测试你的功能。可以将其视为功能的端到端测试。

以下是一个简单的示例：

providers:
  - id: openai:chat:gpt-4o
prompts:
  - Translate "{{input}}" to {{language}}
tests:
  - vars:
      input: 'Hello, world!'
      language: 'English'
    assert:
      - type: new-assertion-type

添加新提供者​

提供者是用 TypeScript 定义的。我们还为 Python 和 Go 提供了语言绑定。要贡献一个新的提供者：

  1. 确保你的提供者尚未存在于 promptfoo 中，并且符合其范围。对于兼容 OpenAI 的提供者，你可能可以重用 openai 提供者并覆盖基本 URL 和其他设置。如果你的提供者兼容 OpenAI，可以跳到第 4 步。

  2. 按照我们的 自定义 API 提供者文档 在 src/providers/yourProviderName.ts 中实现提供者。请使用我们的缓存 src/cache.ts 来存储响应。如果你的提供者需要新的依赖项，请使用 npm install --save-peer 将其添加为对等依赖项。

  3. 在 test/providers.yourProviderName.test.ts 中编写单元测试，并在 examples/ 目录中创建一个示例。

  4. 在 site/docs/providers/yourProviderName.md 中记录你的提供者，包括描述、设置说明、配置选项和使用示例。你也可以在 examples/ 目录中添加示例。考虑编写一篇指南，比较你的提供者与其他提供者，或突出其独特的功能或优势。

  5. 更新 src/providers/index.ts 和 site/docs/providers/index.md 以包含你的新提供者。更新 src/envars.ts 以包含你的提供者可能需要的任何新环境变量。

  6. 确保所有测试通过 (npm test) 并修复任何代码规范问题 (npm run lint)。

贡献到 Web UI​

Web UI 是作为一个 React 应用编写的。它作为静态站点导出，并在打包时由本地 express 服务器托管。

要在开发模式下运行 Web UI：

npm run dev

这将在 http://localhost:3000 上托管 Web UI。这使你可以快速修改 React 应用（支持快速刷新）。如果你想在没有 express 服务器的情况下运行 Web UI，可以运行：

npm run dev:web

要端到端测试整个项目，我们建议构建整个项目并将其链接到 promptfoo：

npm run build
promptfoo view

请注意，如果你对代码进行了进一步更改，这将不会更新 Web UI。你必须再次运行 npm run build。

Python 贡献​

虽然 promptfoo 主要是用 TypeScript 编写的，但我们支持自定义的 Python 提示、提供者、断言以及许多 Python 示例。我们努力保持 Python 代码库简单且最小化，不依赖外部库。请遵循以下准则：

  • 使用 Python 3.9 或更高版本
  • 对于代码规范和格式化，使用 ruff。在提交更改之前运行 ruff check --fix 和 ruff format
  • 遵循 Google Python 风格指南
  • 使用类型提示以提高代码可读性并捕捉潜在错误
  • 使用内置的 unittest 模块为新的 Python 函数编写单元测试
  • 当为示例添加新的 Python 依赖项时，更新相关的 requirements.txt 文件

文档​

如果你正在添加新功能或更改现有功能，请更新相关文档。我们使用 Docusaurus 来编写文档。我们强烈鼓励提供示例和指南。

数据库​

promptfoo 默认使用 SQLite 作为其数据库，通过 Drizzle ORM 进行管理。默认情况下，数据库存储在 /.promptfoo/ 中。你可以通过设置 PROMPTFOO_CONFIG_DIR 来覆盖此位置。数据库模式定义在 src/database.ts 中，迁移存储在 drizzle 中。请注意，迁移是自动生成的，你不应该直接访问这些文件。

主要表​

  • evals：存储评估详情，包括结果和配置。
  • prompts：存储不同提示的信息。
  • datasets：存储数据集信息和测试配置。
  • evalsToPrompts：管理评估与提示之间的关系。
  • evalsToDatasets：管理评估与数据集之间的关系。

你可以通过运行 npx drizzle-kit studio 来查看这些表的内容，这将启动一个 Web 服务器。

添加迁移​

  1. 修改模式：在 src/database.ts 中对你的模式进行更改。

  2. 生成迁移：运行命令以创建新的迁移：

    npm run db:generate

    此命令将在 drizzle 目录中创建一个新的 SQL 文件。

  3. 审查迁移：检查生成的迁移文件，确保它捕获了你预期的更改。

  4. 应用迁移：使用以下命令应用迁移：

    npm run db:migrate

注意：发布版本只能由维护者进行。如果你需要快速发布新版本，请在Discord上发送消息。

作为维护者，当你准备好发布新版本时：

  1. 更新package.json中的版本号。

  2. 运行npm install。

  3. 将更新后的文件添加到Git：

    git add package.json package-lock.json

  4. 提交更改：

    git commit -m "chore: 将版本号更新为0.X.Y"

  5. 将更改推送到主分支：

    git push origin main

  6. GitHub Action会自动创建一个版本标签。版本标签创建后，基于该标签生成一个新的发布版本。

  7. GitHub Action应自动将包发布到npm。如果未自动发布，请手动发布。

获取帮助​

如果你需要帮助或有疑问，可以：

  • 在GitHub上打开一个问题。
  • 加入我们的Discord社区。

行为准则​

我们遵循贡献者公约行为准则。请在社区内的所有互动中阅读并遵守它。