调用元数据

当你想为实时的提示、工作流或智能体运行附加自己的审计字段时,请使用调用元数据。元数据与运行一同存储,在日志详情中显示,并可作为日志中的 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 部分,方便你确认哪些调用方定义的字段附加到了该次运行。

快速开始

Live Chat

提示词

工作流

Hive Agents

智能体

知识库

实验

您的工作区

监控

用户跟踪

资源

调用元数据

调用元数据

概述

元数据结构

cURL 示例

Prompt invoke

Workflow invoke

Agent invoke

SDK 示例

Node.js

Python

Ruby

PHP

按元数据筛选日志

另请参阅

​调用元数据

​概述

​元数据结构

​cURL 示例

​Prompt invoke

​Workflow invoke

​Agent invoke

​SDK 示例

​Node.js

​Python

​Ruby

​PHP

​按元数据筛选日志

​另请参阅

调用元数据

概述

元数据结构

cURL 示例

Prompt invoke

Workflow invoke

Agent invoke

SDK 示例

Node.js

Python

Ruby

PHP

按元数据筛选日志

另请参阅