文档

抢先体验

测试托管工具

用签名的测试调用检查端点,用模拟结果检查模型的选择,然后在 Timeline 中查看真实的请求。

有两件事要测试,各有一个对应的工具:

  • 我的端点能正常工作吗? 使用 Send test call。它会向你的端点发出一次真实的签名调用。
  • 模型能用好我的工具吗? 使用 Playground。它用模拟结果运行整个循环,绝不会调用你的端点。

Send test call

在工作流的 Tools 选项卡上,打开某个工具的 ⋯ 菜单,选择 Send test call。

  1. 选择发送到哪里:Endpoint URL,或 My CLI(通过正在运行的 modelriver tools 会话调用你的本地服务器)。当你有已连接的会话时,会默认选中 My CLI。
  2. 如有需要,编辑 Arguments。它们初始为根据工具的 schema 生成的示例。
  3. 把 End user id 设置为你的测试数据中存在的用户。它会作为 end_user.id 发送。
  4. 选择 Send test call。

ModelRiver 调用端点的方式与真实请求完全一样:用项目的密钥签名,执行相同的地址检查、超时和大小限制。只读取数据的工具在遇到 5xx 或连接中断后会重试一次,与真实请求相同;会修改数据的工具绝不会重试。请求体的 request 中带有 "mode": "test",因此你的端点可以区分测试和生产流量。

你会看到调用是否成功、HTTP 状态和耗时、模型将读取到的结果,以及所发送的请求头和请求体。签名值本身不会显示:它连同请求体,就是一个你的端点在五分钟内会接受的请求。要用已知的签名检查你的验证器,请使用测试值。

除非你预期会收到,否则你的生产端点应当拒绝带有 "mode": "test" 的调用,这样测试调用就不会对线上数据产生任何操作。

注意事项:

  • 工具取自表单,因此你可以在保存之前测试一个工具,或对工具的修改。
  • 参数会先按工具的 schema 检查,与模型给出的参数一样,并且最大可达 16 KB。
  • 项目需要有签名密钥。
  • 组织所有者和管理员可以发送测试调用,每人每分钟最多 20 次,每个组织每小时最多 300 次。每次调用都会记录在审计日志中,并附上端点的主机。
  • 测试调用不算作套餐中的请求。
  • 选择 My CLI 时,调用只会发往你自己已连接的会话(绝不会发往队友的会话),使用本地服务器上与工具端点 URL 相同的路径,并且绝不重试。端点的主机不会被调用。请参阅测试本地端点。
  • 对于会更改内容的工具,测试调用不会请求审批,因此你可以在写审批提示之前先试用端点。它会真正调用端点一次,并且绝不重试,所以请把它指向测试数据。

Playground

在 Playground 中选择该工作流,并打开 Async mode。之后的运行会经过工具循环:模型看到你的工具、做出选择、拿到结果并作答。

Playground 绝不会调用工具上保存的端点。每个工具改为返回一个模拟结果,除非你用 CLI 把调用发送到你自己的机器:

  • 默认情况下,工具会原样返回模型发送的参数,这样你可以看到它请求了什么。
  • 要指定工具返回什么,请在载荷中添加 tool_mocks,以工具名称为键:
JSON
1{
2 "messages": [
3 { "role": "user", "content": "How did we do this week, and what sold best?" }
4 ],
5 "tool_mocks": {
6 "get_sales_summary": { "period": "this_week", "revenue": 48200, "orders": 912, "change_vs_previous": 0.12 },
7 "get_top_products": { "products": [{ "name": "Desk lamp", "units": 310 }] }
8 }
9}

工作流下方的提示中有一个链接,可以添加一个 tool_mocks 块,其中每个工具一个条目。

这是调整工具描述最快的方法:修改描述,运行同一个问题,看模型是否用正确的参数选择了正确的工具。模型的参数仍会按每个工具的 schema 检查。

注意事项:

  • 仅限 Async mode。 不开启它时,Playground 会在不带你的工具的情况下运行模型,并会给出说明。
  • Playground 运行不需要 end_user,也不计为请求。
  • Run 选项(Auto、Draft、Live 或 Historical)决定运行哪个修订版本的工具,因此你可以在发布前试用 Draft 的工具。
  • 处于测试模式的工作流会返回其示例数据,完全不运行任何工具。

Playground 中的审批

在 Playground 中,对会更改内容的工具的调用同样会等待审批,就像对终端用户那样。运行会暂停,下方会出现一张卡片,显示工具的审批提示和在 Show to the user 下勾选的参数,带有 Approve 和 Decline 按钮以及等待结束的时间。

  • Approve: 本轮所有等待中的调用都决定后,这次调用会得到模拟结果(来自 tool_mocks,或回显的参数),运行随后继续。如果这次运行把工具调用发送到你的 CLI,已批准的调用则会被发送到你的本地端点,只发送一次,绝不重试。
  • Decline: 这次调用不会运行,模型会被告知用户拒绝了它。
  • 无人回应: 超过工作流的 Approval wait 后,调用会过期,模型会被告知没有人回应。

用它检查终端用户将看到的内容:提示是否通顺,展示的参数是否足以做决定。注意事项:

  • Playground 中的调用只能在控制台中决定,由可以在该项目上运行 Playground 的人操作。对于这些调用,公开的批准和拒绝端点会返回 404。
  • Playground 运行不会发送 tool.approval_required webhook。
  • 如果在调用等待期间重新加载页面,卡片会重新出现。
  • 在请求日志中,决定会显示为 Approved in the Playground 或 Declined in the Playground。

测试本地端点

ModelRiver 从自己的服务器调用工具端点,因此保存的 Endpoint URL 必须是公网 HTTPS 地址。保存工具时,http://localhost:3000 会被拒绝。

要试用运行在你机器上的端点,请让 ModelRiver CLI 把调用转送过去:

Bash
modelriver tools --forward-to http://localhost:3000

CLI 会打印一个会话 id。它运行期间:

  • 在 Playground 中,在工作流下方(Async mode)打开 Send tool calls to my CLI。
  • 从你自己的后端,把该会话加入请求:
JSON
1{
2 "workflow": "sales_chat",
3 "messages": [{ "role": "user", "content": "How did we do this week?" }],
4 "end_user": { "id": "user_812" },
5 "tool_route": { "cli_session": "cts_…" }
6}

每次工具调用的构建和签名都与发往真实端点时完全一样,CLI 会把它 POST 到你机器上的相同路径:保存为 https://api.example.com/tools/sales 的工具,会在 http://localhost:3000/tools/sales 被调用。你的端点的应答会回到模型。请求体的 request 中带有 "via": "cli"。

注意事项:

  • CLI 只会转发到你自己的机器(localhost、127.0.0.1 或 ::1)。
  • 会话有效期 24 小时,属于 CLI 所用 API 密钥所在的项目,并属于该密钥的所有者。请求只能指定自己项目的会话。Playground 会提供用你创建的 API 密钥开启的会话,因此请谨慎分享密钥。
  • 用相同的 API 密钥和 --forward-to 再次启动 modelriver tools 会重新加入它原有的会话,因此指定了该会话的请求在重启后仍可继续使用。每人每个项目最多可同时连接 5 个会话;再开启新的会占用已不再连接的会话的名额。
  • 如果 CLI 没有运行,指定了它的会话的请求会被拒绝(409 cli_session_not_connected)。如果它中途停止,已发给它的调用会超时,后续调用会立即以不可用失败。调用绝不会改为发送到保存的端点。
  • 通过 CLI 的运行要等待你的机器,因此它会计入项目对同时运行的 hosted-tools 请求的限制,Playground 中的运行也一样。
  • 使用 CLI 的请求是普通请求:它们计入你的套餐,响应的 meta.tool_loop 中带有 "via": "cli"。在 Timeline 中,每次调用都标有 via CLI。
  • 部署前请移除 tool_route。生产请求绝不应指定 CLI 会话,并且你的生产端点应拒绝带有 "via": "cli" 的调用(参见安全)。

如果你更想暴露端点本身,可以使用隧道,例如 cloudflared tunnel --url http://localhost:3000 或 ngrok http 3000,它会给端点一个公网 HTTPS 地址,保存到工具上即可。请保持签名验证开启:隧道运行期间,其地址是公开的。

为开发单独使用一个项目,配上它自己的签名密钥,以及指向预发布后端的工具,可以让测试流量远离生产环境。

在 Timeline 中查看请求

打开 Request Logs 并选择一个请求。对于带有托管工具的请求,Timeline 会显示:

  • 每个模型轮次,并标明模型做了什么:请求了工具,或给出了回答。
  • 每个轮次下的每次工具调用:工具、结果(ok、error、timeout,会更改内容的工具还可能是 unknown)、HTTP 状态、耗时和尝试次数。
  • 对于会更改内容的工具的调用,显示它的审批及时间:被终端用户批准、被拒绝、未及时回应,或因请求被停止而没有运行。请求等待期间,暂停的那一轮会单独显示,并标注 Waiting for approval, until 等待结束的时间。
  • 对于失败的调用,显示原因:例如参数与 schema 不匹配,或端点返回了 503。
  • 项目开启 Save full request and response text 后,还会在 Arguments and result 下显示每次调用的参数和结果。
  • 通过 CLI 应答的调用,标有 via CLI。

请求列表会显示每个请求用了多少个工具轮次,费用面板会把各轮次加总。Playground 运行中以模拟结果应答的调用会标记为 Mock。

上线前的检查清单

  • 端点会拒绝签名错误的调用,以及时间戳过旧的调用。
  • 端点从 end_user 读取是谁在请求,对于它不认识的用户不返回任何内容。
  • 每个工具的 schema 都有 "additionalProperties": false。
  • 结果很小:只包含模型需要的字段。
  • 在负载下,端点能远在超时时间之内应答。
  • 前端会显示进度、处理 error.type,并有一个停止按钮。
  • 对每个会更改内容的工具:审批提示说清楚将会发生什么,展示的参数足以做决定,你的批准路由从会话中取得 end_user.id,并且端点处理重复的调用 id 时不会把操作执行两次。

下一步