OpenAI

要使用 OpenAI API，请设置 OPENAI_API_KEY 环境变量，通过配置文件中的 apiKey 字段指定，或将 API 密钥作为构造函数的参数传递。

示例：

export OPENAI_API_KEY=your_api_key_here

OpenAI 提供程序支持以下模型格式：

• openai:chat - 默认为 gpt-4o-mini
• openai:completion - 默认为 text-davinci-003
• openai:<model name> - 使用特定模型名称（自动映射到聊天或完成端点）
• openai:chat:<model name> - 使用任何模型名称针对 /v1/chat/completions 端点
• openai:chat:ft:gpt-4o-mini:company-name:ID - 微调聊天完成模型的示例
• openai:completion:<model name> - 使用任何模型名称针对 /v1/completions 端点
• openai:embeddings:<model name> - 使用任何模型名称针对 /v1/embeddings 端点
• openai:assistant:<assistant id> - 使用助手

openai:<endpoint>:<model name> 构造在 OpenAI 发布新模型或您有自定义模型时非常有用。例如，如果 OpenAI 发布 gpt-5 聊天完成模型，您可以立即使用 openai:chat:gpt-5。

OpenAI 提供程序支持一些配置选项，例如 temperature、functions 和 tools，可用于自定义模型的行为，如下所示：

providers:
  - id: openai:gpt-4o-mini
    config:
      temperature: 0
      max_tokens: 1024

格式化聊天消息

有关设置聊天对话的信息，请参阅聊天线程。

配置参数

providers 列表接受一个 config 键，允许您设置 temperature、max_tokens 等参数。例如：

providers:
  - id: openai:gpt-4o-mini
    config:
      temperature: 0
      max_tokens: 128
      apiKey: sk-abc123

支持的参数包括：

参数	描述
apiBaseUrl	OpenAI API 的基本 URL，请同时阅读下面的 OPENAI_BASE_URL。
apiHost	OpenAI API 的主机名，请同时阅读下面的 OPENAI_API_HOST。
apiKey	您的 OpenAI API 密钥，等同于 OPENAI_API_KEY 环境变量
apiKeyEnvar	包含 API 密钥的环境变量
best_of	控制生成的替代输出的数量，并从中选择。
frequency_penalty	对频繁的标记应用惩罚，使它们不太可能在输出中出现。
function_call	控制 AI 是否应调用函数。可以是 'none'、'auto'，或一个带有指定要调用的函数的 name 的对象。
functions	允许您定义自定义函数。每个函数应为一个带有 name、可选的 description 和 parameters 的对象。
functionToolCallbacks	函数工具名称到函数回调的映射。每个回调应接受一个字符串并返回一个字符串或 Promise<string>。
headers	要在请求中包含的附加标头。
max_tokens	控制输出的最大长度（以标记为单位）。
organization	您的 OpenAI 组织密钥。
passthrough	传递给API的额外参数。
presence_penalty	对新标记（未在输入中出现的标记）应用惩罚，使其在输出中出现的可能性降低。
response_format	指定所需的输出格式，包括 json_object 和 json_schema
seed	用于确定性输出的种子。
stop	定义一个标记列表，这些标记表示输出的结束。
temperature	控制AI输出的随机性。较高的值（接近1）使输出更随机，而较低的值（接近0）使其更具确定性。
tool_choice	控制AI是否应使用工具。参见 OpenAI Tools文档
tools	允许您定义自定义工具。参见 OpenAI Tools文档
top_p	控制核采样，这是一种帮助控制AI输出随机性的方法。

以下是 config 参数的类型声明：

interface OpenAiConfig {
  // 完成参数
  temperature?: number;
  max_tokens?: number;
  top_p?: number;
  frequency_penalty?: number;
  presence_penalty?: number;
  best_of?: number;
  functions?: OpenAiFunction[];
  function_call?: 'none' | 'auto' | { name: string };
  tools?: OpenAiTool[];
  tool_choice?: 'none' | 'auto' | 'required' | { type: 'function'; function?: { name: string } };
  response_format?: { type: 'json_object' | 'json_schema'; json_schema?: object };
  stop?: string[];
  seed?: number;
  passthrough?: object;

  // 函数工具回调
  functionToolCallbacks?: Record<
    OpenAI.FunctionDefinition['name'],
    (arg: string) => Promise<string>
  >;

  // 通用OpenAI参数
  apiKey?: string;
  apiKeyEnvar?: string;
  apiHost?: string;
  apiBaseUrl?: string;
  organization?: string;
  headers?: { [key: string]: string };
}

图像

在提示中发送图像

您可以通过使用内容块在提示中包含图像。例如，以下是一个示例配置：

prompts:
  - prompt.json

providers:
  - openai:gpt-4o

tests:
  - vars:
      question: 'What do you see?'
      url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg'
  # ...

以及一个示例 prompt.json：

[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "{{question}}"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "{{url}}"
        }
      }
    ]
  }
]

参见 OpenAI vision示例。

生成图像

OpenAI 支持通过 openai:image:dalle-3 生成图像。参见 OpenAI Dall-E示例。

prompts:
  - 'In the style of Van Gogh: {{subject}}'
  - 'In the style of Dali: {{subject}}'

providers:
  - openai:image:dall-e-3

tests:
  - vars:
      subject: bananas
  - vars:
      subject: new york city

要在网页查看器中显示图像，请将变量或输出包装在markdown图像标签中，如下所示：

![](/path/to/myimage.png)

然后，在表格设置下启用“渲染markdown”。

使用工具和函数

OpenAI 工具和函数均受支持。参见 OpenAI tools示例 和 OpenAI functions示例。

使用工具

要在OpenAI提供程序上设置 tools，请使用提供程序的 config 键。在此键下添加您的函数定义。

prompts:
  - file://prompt.txt
providers:
  - id: openai:chat:gpt-4o-mini
    config:
      tools: [
        {
        "type": "function",
          "function": {
            "name": "get_current_weather",
            "description": "获取指定位置的当前天气",
            "parameters": {
              "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                      "description": "城市和州，例如：San Francisco, CA"
                    },
                    "unit": {
                      "type": "string",
                      "enum": ["celsius", "fahrenheit"]
                    }
                  },
              "required": ["location"]
            }
          }
        }
      ]
      tool_choice: 'auto'

tests:
   - vars:
        city: Boston
     assert:
        - type: is-json
        - type: is-valid-openai-tools-call
        - type: javascript
          value: output[0].function.name === 'get_current_weather'
        - type: javascript
          value: JSON.parse(output[0].function.arguments).location === 'Boston, MA'

   - vars:
        city: New York
# ...

有时OpenAI的函数调用与tools模式不匹配。使用is-valid-openai-tools-call或is-valid-openai-tools-call断言来强制工具与函数定义之间的模式完全匹配。

为了进一步测试tools定义，你可以使用javascript断言和/或transform指令。例如：

tests:
  - vars:
      city: Boston
    assert:
      - type: is-json
      - type: is-valid-openai-tools-call
      - type: javascript
        value: output[0].function.name === 'get_current_weather'
      - type: javascript
        value: JSON.parse(output[0].function.arguments).location === 'Boston, MA'

  - vars:
      city: New York
      # transform 仅返回 'name' 属性
    transform: output[0].function.name
    assert:
      - type: is-json
      - type: similar
        value: NYC

tip

函数可以使用测试用例中的变量：

{
  type: "function",
  function: {
    description: "获取{{city}}的温度"
    // ...
  }
}

它们还可以包含动态引用变量的函数：

{
  type: "function",
  function: {
    name: "get_temperature",
    parameters: {
      type: "object",
        properties: {
          unit: {
            type: "string",
            enum: (vars) => vars.units,
          }
        },
    }
  }
}

使用函数

functions 和 function_call 已被弃用，取而代之的是 tools 和 tool_choice，详情请参见 OpenAI API 参考。

使用 functions 配置来定义自定义函数。每个函数应为一个包含 name、可选的 description 和 parameters 的对象。例如：

prompts:
  - file://prompt.txt
providers:
  - id: openai:chat:gpt-4o-mini
    config:
      functions:
        [
          {
            'name': 'get_current_weather',
            'description': '获取指定位置的当前天气',
            'parameters':
              {
                'type': 'object',
                'properties':
                  {
                    'location':
                      {
                        'type': 'string',
                        'description': '城市和州，例如：San Francisco, CA',
                      },
                    'unit': { 'type': 'string', 'enum': ['celsius', 'fahrenheit'] },
                  },
                'required': ['location'],
              },
          },
        ]
tests:
  - vars:
      city: Boston
    assert:
      - type: is-valid-openai-function-call
  - vars:
      city: New York
  # ...

有时OpenAI的函数调用与functions模式不匹配。使用is-valid-openai-function-call断言来强制函数调用与函数定义之间的模式完全匹配。

为了进一步测试函数调用定义，你可以使用javascript断言和/或transform指令。例如：

tests:
  - vars:
      city: Boston
    assert:
      - type: is-valid-openai-function-call
      - type: javascript
        value: output.name === 'get_current_weather'
      - type: javascript
        value: JSON.parse(output.arguments).location === 'Boston, MA'

  - vars:
      city: New York
    # transform 仅返回此测试用例的 'name' 属性
    transform: output.name
    assert:
      - type: is-json
      - type: similar
        value: NYC

从文件加载工具/函数

与其在多个配置中重复定义函数，你可以引用包含函数的外部YAML（或JSON）文件。这允许你为函数维护单一的真实来源，如果你有多个版本或定义的频繁更改，这尤其有用。

要从文件加载函数，请在你的提供者配置中指定文件路径，如下所示：

providers:
  - file://./path/to/provider_with_function.yaml

你也可以使用模式加载多个文件：

providers:
  - file://./path/to/provider_*.yaml

以下是你可能的 provider_with_function.yaml 文件示例：

id: openai:chat:gpt-4o-mini
config:
  functions:
    - name: get_current_weather
      description: 获取指定地点的当前天气
      parameters:
        type: object
        properties:
          location:
            type: string
            description: 城市和州，例如：San Francisco, CA
          unit:
            type: string
            enum:
              - celsius
              - fahrenheit
            description: 返回温度的单位
        required:
          - location

使用 response_format

Promptfoo 支持 response_format 参数，允许您指定预期的输出格式。

response_format 可以包含在提供者配置中，也可以包含在提示配置中。

提示配置示例

prompts:
  - label: '提示 #1'
    raw: '你是一个有帮助的数学导师。解决 {{problem}}'
    config:
      response_format:
        type: json_schema
        json_schema: ...

提供者配置示例

providers:
  - id: openai:chat:gpt-4o-mini
    config:
      response_format:
        type: json_schema
        json_schema: ...

外部文件引用

为了更方便地管理大型 JSON 模式，支持外部文件引用：

config:
  response_format: file://./path/to/response_format.json

支持的环境变量

这些与 OpenAI 相关的环境变量受支持：

变量	描述
OPENAI_TEMPERATURE	温度模型参数，默认为 0。o1-models 不支持。
OPENAI_MAX_TOKENS	max_tokens 模型参数，默认为 1024。o1-models 不支持。
OPENAI_MAX_COMPLETION_TOKENS	max_completion_tokens 模型参数，默认为 1024。o1-models 使用。
OPENAI_API_HOST	要使用的域名（如果您使用 API 代理，这很有用）。优先于 OPENAI_BASE_URL。
OPENAI_BASE_URL	要使用的基本 URL（协议 + 域名 + 端口），这是一个比 OPENAI_API_HOST 更通用的选项。
OPENAI_API_KEY	OpenAI API 密钥。
OPENAI_ORGANIZATION	要使用的 OpenAI 组织密钥。
PROMPTFOO_DELAY_MS	API 调用之间的延迟毫秒数。如果您遇到 OpenAI 速率限制，这很有用（默认为 0）。
PROMPTFOO_REQUEST_BACKOFF_MS	请求失败时退避和重试的基础毫秒数（默认为 5000）。

评估助手

要通过 OpenAI 的 Assistants API 测试助手，首先在 API 游乐场 中创建一个助手。

根据需要设置函数、代码解释器和文件检索。

然后，在您的配置中包含该助手：

prompts:
  - '写一条关于 {{topic}} 的推文'
providers:
  - openai:assistant:asst_fEhNN3MClMamLfKLkIaoIpgZ
tests:
  - vars:
      topic: bananas
  # ...

代码解释器、函数调用和检索将包含在聊天消息的输出中。请注意，评估器为每个评估创建一个新线程。

以下属性可以在提供者配置中覆盖：

• model - 要使用的 OpenAI 模型
• instructions - 系统提示
• tools - 启用的 工具
• thread.messages - 创建线程时使用的消息对象列表。
• temperature - 模型的温度
• toolChoice - 控制 AI 是否应使用工具
• attachments - 要包含在消息中的文件附件 - 参见 Assistant v2 附件

以下是一个更详细配置的示例：

prompts:
  - '写一条关于 {{topic}} 的推文'
providers:
  - id: openai:assistant:asst_fEhNN3MClMamLfKLkIaoIpgZ
    config:
      model: gpt-4o
      instructions: "你总是像海盗一样说话"
      temperature: 0.2
      toolChoice:
        type: file_search
      tools:
        - type: code_interpreter
        - type: file_search
      thread:
        messages:
          - role: user
            content: "你好，世界"
          - role: assistant
            content: "来自大海的问候"
tests:
  - vars:
      topic: bananas
  # ...

自动处理函数工具调用

您可以指定 JavaScript 回调函数，这些函数会自动调用以创建函数工具调用的输出。

这需要在 JavaScript 文件中定义您的配置，而不是 YAML。

module.exports = /** @type {import('promptfoo').TestSuiteConfig} */ ({
  prompts: '请将以下数字相加：{{a}} 和 {{b}}',
  providers: [
    {
      id: 'openai:assistant:asst_fEhNN3MClMamLfKLkIaoIpgZ',
      config:
        /** @type {InstanceType<import('promptfoo')["providers"]["OpenAiAssistantProvider"]>["config"]} */ ({
          model: 'gpt-4o',
          instructions: '你可以使用 `addNumbers` 工具将两个数字相加',
          tools: [
            {
              type: 'function',
              function: {
                name: 'addNumbers',
                description: '将两个数字相加',
                parameters: {
                  type: 'object',
                  properties: {
                    a: { type: 'number' },
                    b: { type: 'number' },
                  },
                  required: ['a', 'b'],
                },
              },
            },
          ],
          /**
           * 函数工具名称到函数回调的映射。
           */
          functionToolCallbacks: {
            // 此函数应接受一个字符串，并返回一个字符串
            // 或一个 `Promise<string>`。
            addNumbers: (parametersJsonString) => {
              const { a, b } = JSON.parse(parametersJsonString);
              return JSON.stringify(a + b);
            },
          },
        }),
    },
  ],
  tests: [
    {
      vars: { a: 5, b: 6 },
    },
  ],
});

故障排除

OpenAI 速率限制

如果你遇到 OpenAI 的速率限制（最常见于 GPT-4），可以尝试以下几种方法：

1. 将并发数减少到 1，通过在命令行中设置 --max-concurrency 1，或在配置中设置 evaluateOptions.maxConcurrency。
2. 在请求之间设置延迟，通过在命令行中设置 --delay 3000（3000 毫秒），或在配置中设置 evaluateOptions.delay，或通过环境变量 PROMPTFOO_DELAY_MS（所有值以毫秒为单位）。
3. 调整失败请求的指数退避，通过设置环境变量 PROMPTFOO_REQUEST_BACKOFF_MS。默认值为 5000 毫秒，最多重试 4 次。如果请求仍然失败，可以增加此值，但请注意，这会显著增加端到端测试时间。

OpenAI 不稳定

要重试返回内部服务器错误的 HTTP 请求，请将环境变量 PROMPTFOO_RETRY_5XX 设置为 1。