跳转到主要内容

​
调用元数据

当你想为实时的提示、工作流或智能体运行附加自己的审计字段时,请使用调用元数据。元数据与运行一同存储,在日志详情中显示,并可作为日志中的 User metadata 筛选条件使用。

​
概述

Fetch Hive 在以下公开 invoke 端点上接受 metadata 对象:
  • POST /v1/prompt/invoke
  • POST /v1/workflow/invoke
  • POST /v1/agent/invoke
将元数据用于来自你应用的字段,帮助你之后调查和细分流量,例如客户 ID、套餐名称、区域、实验名称、环境、租户 ID 或功能开关。 元数据不是提示、工作流或智能体的输入。提示变量和工作流启动变量属于 inputs。智能体消息属于 message 或 messages。

​
元数据结构

metadata 必须是一个扁平对象。键必须是非空字符串,值必须是字符串、数字、布尔值或 null。 嵌套对象和数组会在运行开始之前被拒绝。 良好的元数据示例: 
{
  "customer_id": "cus_123",
  "plan": "enterprise",
  "region": "us-east-1",
  "experiment": "checkout_v2",
  "beta_user": true
}
避免在元数据中发送敏感数据、密钥、原始用户消息或大型负载。保持其小巧且稳定,以便筛选器持续有用。

​
cURL 示例

​
Prompt invoke

curl 'https://api.fetchhive.com/v1/prompt/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "deployment": "support-classifier",
    "variant": "default",
    "inputs": {
      "ticket_text": "The export button is disabled."
    },
    "metadata": {
      "customer_id": "cus_1234",
      "plan": "enterprise",
      "experiment": "support_triage_v2"
    }
  }'

​
Workflow invoke

curl 'https://api.fetchhive.com/v1/workflow/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "deployment": "research-brief",
    "variant": "default",
    "inputs": {
      "topic": "AI infrastructure trends"
    },
    "metadata": {
      "customer_id": "cus_123",
      "region": "us-east-1",
      "source": "daily_digest_job"
    }
  }'

​
Agent invoke

curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Summarize this account before renewal.",
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise",
      "renewal_window_days": 30
    }
  }'

​
SDK 示例

官方 SDK 在提示、工作流和智能体 invoke 辅助方法上接受相同的 metadata 对象。

​
Node.js

import { FetchHive } from "@fetch-hive/sdk";

const client = new FetchHive({ apiKey: process.env.FETCH_HIVE_API_KEY });

const result = await client.invokePrompt({
  deployment: "support-classifier",
  variant: "default",
  inputs: { ticket_text: "The export button is disabled." },
  metadata: {
    customer_id: "cus_123",
    plan: "enterprise",
    experiment: "support_triage_v2",
  },
});

console.log(result.response);
在 invokeWorkflow 和 invokeAgent 中使用相同的字段: 
await client.invokeWorkflow({
  deployment: "research-brief",
  variant: "default",
  inputs: { topic: "AI infrastructure trends" },
  metadata: { customer_id: "cus_123", source: "daily_digest_job" },
});

await client.invokeAgent({
  agent: "AGENT_UUID",
  message: "Summarize this account before renewal.",
  metadata: { customer_id: "cus_123", renewal_window_days: 30 },
});

​
Python

from fetch_hive_sdk import FetchHive

client = FetchHive()

result = client.invoke_prompt(
    deployment="support-classifier",
    variant="default",
    inputs={"ticket_text": "The export button is disabled."},
    metadata={
        "customer_id": "cus_123",
        "plan": "enterprise",
        "experiment": "support_triage_v2",
    },
)

print(result["response"])
在 invoke_workflow 和 invoke_agent 中使用相同的参数: 
client.invoke_workflow(
    deployment="research-brief",
    variant="default",
    inputs={"topic": "AI infrastructure trends"},
    metadata={"customer_id": "cus_123", "source": "daily_digest_job"},
)

client.invoke_agent(
    agent="AGENT_UUID",
    message="Summarize this account before renewal.",
    metadata={"customer_id": "cus_123", "renewal_window_days": 30},
)

​
Ruby

require "fetch_hive"

client = FetchHive::Client.new(api_key: ENV.fetch("FETCH_HIVE_API_KEY"))

result = client.invoke_prompt(
  deployment: "support-classifier",
  variant: "default",
  inputs: { ticket_text: "The export button is disabled." },
  metadata: {
    customer_id: "cus_123",
    plan: "enterprise",
    experiment: "support_triage_v2"
  }
)

puts result["response"]

​
PHP

<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive(['api_key' => getenv('FETCH_HIVE_API_KEY')]);

$result = $client->invokePrompt([
    'deployment' => 'support-classifier',
    'variant'    => 'default',
    'inputs'     => ['ticket_text' => 'The export button is disabled.'],
    'metadata'   => [
        'customer_id' => 'cus_123',
        'plan'        => 'enterprise',
        'experiment'  => 'support_triage_v2',
    ],
]);

echo $result['response'];

​
按元数据筛选日志

在带有元数据的运行到达后,打开对应的日志页面:
  • 提示运行:打开提示并选择 Activity Logs
  • 工作流运行:打开 Workflows 并选择 Logs
  • 智能体运行:打开 Agents 并选择 Logs
使用 User metadata 按元数据进行筛选。 选择一个元数据键以查找该键存在的运行。当你想要精确的标量匹配时,可添加一个值,例如 customer_id = cus_123、plan = enterprise、beta_user = true 或 renewal_window_days = 30。 Fetch Hive 会随时间从 invoke 请求中跟踪元数据属性名称,以便筛选器能够建议你的工作区实际发送过的键。没有该元数据的早期运行仍可正常查看,但在匹配的元数据筛选器处于激活状态时会被排除。 当你打开一个运行详情面板时,元数据会出现在 User metadata 部分,方便你确认哪些调用方定义的字段附加到了该次运行。

​
另请参阅