有两件事要测试,各有一个对应的工具:
- 我的端点能正常工作吗? 使用 Send test call。它会向你的端点发出一次真实的签名调用。
- 模型能用好我的工具吗? 使用 Playground。它用模拟结果运行整个循环,绝不会调用你的端点。
Send test call
在工作流的 Tools 选项卡上,打开某个工具的 ⋯ 菜单,选择 Send test call。
- 选择发送到哪里:Endpoint URL,或 My CLI(通过正在运行的
modelriver tools会话调用你的本地服务器)。当你有已连接的会话时,会默认选中 My CLI。 - 如有需要,编辑 Arguments。它们初始为根据工具的 schema 生成的示例。
- 把 End user id 设置为你的测试数据中存在的用户。它会作为
end_user.id发送。 - 选择 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,以工具名称为键:
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_requiredwebhook。 - 如果在调用等待期间重新加载页面,卡片会重新出现。
- 在请求日志中,决定会显示为 Approved in the Playground 或 Declined in the Playground。
测试本地端点
ModelRiver 从自己的服务器调用工具端点,因此保存的 Endpoint URL 必须是公网 HTTPS 地址。保存工具时,http://localhost:3000 会被拒绝。
要试用运行在你机器上的端点,请让 ModelRiver CLI 把调用转送过去:
modelriver tools --forward-to http://localhost:3000CLI 会打印一个会话 id。它运行期间:
- 在 Playground 中,在工作流下方(Async mode)打开 Send tool calls to my CLI。
- 从你自己的后端,把该会话加入请求:
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 时不会把操作执行两次。