常见问题
常见问题
面向运维的回答。演示鉴权、SDK 状态与性能限定保持明确。
快速开始
FluxMeter 是什么？
FluxMeter 是开源、可自托管的实时、token 原生计量引擎，面向 AI API、Token 中转与多租户网关。摄入用量、按模型计价、按下游客户查询成本 — 硬闸与 Intelligence 为同一数据上的可选能力。
FluxMeter 与 OpenMeter 或 Lago 有何不同？
OpenMeter、Lago、Metronome 偏用量→开票；FluxMeter 偏 runtime 计量正确性 + 可选硬闸（check / kill）。我们与开票平台互补 — 不替代开票、税务或 Merchant of Record。
可以自托管 FluxMeter 吗？
可以。make demo 通过 docker-compose 本地启动唯一支持栈。Apache 2.0 许可证，无供应商锁定。
怎样用最少代码完成集成？
使用仓库内 Python SDK（2.0.1 — 未复核包索引是否已发布）。经 HTTP Custody 使用 FluxMeter(api_url=...)，再 wrap(OpenAI(), meter, customer_id=...)。wrap() 负责请求前 check、调用后 track；需明确配置 fail_open，计量失败会告警并可触发 on_metering_error。check 不创建预留，缓存回退与流式估算不保证零超支。层级预留用 reserve(parent_span_id=) / reconcile(parent_span_id=)。不存在 kafka_brokers 客户端 SDK 路径。
什么是 FluxMeter Intelligence？
/intelligence/* 下的启发式 / 规则型 API — 根因分解、单位经济、情景模拟、定价建议、利润视图、预测、告警与报表导出。读取原生用量/成本汇总；收入可来自 OpenMeter 叠加或手动 POST。不是机器学习咨询平台。
FluxMeter 会替代 OpenMeter 或 Langfuse 吗？
不会。FluxMeter 与它们互补：OpenMeter/Lago 负责发票；Langfuse/Helicone 负责可观测性。Intelligence 叠加收入与成本；计量层可导出事件或在热路径拦截。详见 /market-map 市场地图。
计量层还在维护吗？
是的。实时 token 计量（ingest、计价、客户用量查询、HTTP Custody、Gateway）是核心产品。可选硬闸与 Intelligence 建立在相同数据之上 — 不会替代计量。
计量与归因
能否在不建数仓的情况下查询客户账单用量？
可以。GET /usage/customer/{id}/period/{YYYY-MM} 查月度用量，GET /usage/customer/{id}/day/{YYYY-MM-DD} 查日用量，GET /usage/session/{id} 查会话/项目成本（sessionId）。Agent 任务通过 parentSpanId 配合 GET /usage/span/{id} — 受支持栈上由 Flink SpanSink 聚合 span。自 v2.8 起可白名单 metadata 维度，并用 GET /usage/dim/{key}/{value}?period=YYYY-MM 按功能或工作流切片。
如何把用量归因到产品功能或工作流？
v2.8 在 /ingest 接受 metadata 对象（键由 FLUXMETER_USAGE_DIMS 白名单）。用 GET /usage/dim/{key}/{value}?period=YYYY-MM 按功能开关、房间或工作流标签切片查询 — 无需数仓。
FluxMeter 支持哪些 LLM Provider？
内置 OpenAI、Anthropic、Google 模型定价，以及 20 个中国本土模型（DeepSeek、通义千问、GLM、Moonshot、豆包、百川、MiniMax、混元）。Python SDK 提供 track_* 辅助函数；JavaScript SDK 在仓库内提供，尚未发布到 npm。Google 模型可通过通用 provider 字段上报。
Intelligence 的单位经济需要什么数据？
成本来自 FluxMeter 原生摄入汇总。收入需要 OpenMeter 叠加摄入或 POST /intelligence/revenue/{customer_id}。无收入数据的客户返回 status unknown_revenue 及连接提示。
预算与控制
FluxMeter 支持流式 LLM 响应吗？
支持。流式输出前调用 POST /budget/{id}/reserve，流结束后 POST /ingest 和 POST /reconcile。有效余额会扣除进行中的流式预留。自 v2.8 起可在 reserve 上传 parent_span_id，同时占用客户钱包与 span 封顶池。Python wrap() 在预估成本超过预留时会在流中抛出 StreamKilledError（SDK 1.5.0）。
能否按 Agent 任务或会话硬封顶？
可以。v2.7 新增 POST /budget/{id}/cap，kind 为 span 或 session。在 GET /budget/{id}/check 上传 parent_span_id 或 session_id；超额返回 reason=hierarchy_cap。v2.8 增加层级 reserve-confirm：POST /budget/{id}/reserve?parent_span_id= 会原子占用客户余额与 span 封顶池。
支持栈上预算 Webhook 可用吗？
可以。告警路径为 Flink → Kafka budget-alerts → webhook worker。支持 BUDGET_LOW、BUDGET_EXHAUSTED 与 BUDGET_WARN（消耗达 initial_balance + topups 的 70%/90%）。通过 POST /budget/{id}/webhook 配置。
能否按客户 API Key 设置预算？
可以。v2.8 新增 POST /admin/customers/{id}/apikeys/{key_id}/budget。当请求使用该客户 API Key 鉴权时，GET /budget/{id}/check 会在客户钱包之外额外执行按 Key 预算。
运行时与性能
FluxMeter 预算检查有多快？
请求前预算检查的延迟仍是设计目标，不是已发布 SLA。独立的 HTTP ingest 压测在 30 分钟内接受 10,034.90 events/s，p50 36ms / p99 173ms，并有 0.149% 生成器 offered 丢弃。保留配置下完整管线达到 7,772.28 events/s、p50 222ms / p99 1,472ms，因此 10K 门槛仍未达到。见引擎 docs/load-testing.md。
计费导出与集成
FluxMeter 支持哪些计费平台？
FluxMeter 可导出用量到 Stripe Meters、Metronome、Orb、Lago、OpenMeter 和 Zuora。v2.8 提供一等公民 Metronome/Orb/Stripe 导出（BILLING_EXPORT_TARGETS）、通用 POST /admin/billing/{id}/link，以及 docs/integrations/ 下的示例配方（非合作伙伴关系）。支持分层定价与预付费 Token 包。FluxMeter 负责拦截；计费平台仍是发票账本。
安全与运维
本地演示是否可以暴露到公网？
默认不可以。HTTP Custody 演示 compose 可能默认关闭鉴权（FLUXMETER_AUTH_OPTIONAL）。对公网或共享环境暴露前请启用 API Key（并建议使用 fail-closed 预算策略）。生产加固由运维方负责。