Dietary Supplement Analysis (NIH data)

膳食补充剂标签与营养素摄入量分析

当有人询问“我的补充剂方案合适吗？”时，AI 助手会调用此服务。只需像普通人那样提供产品信息（产品名称、条形码或 NIH 标签 ID），以及年龄和性别；还可选择提供用药情况、健康状况和饮食信息。服务会在 NIH 膳食补充剂标签数据库中查找每个标签，汇总所有产品中每天摄入的各种维生素和矿物质，并与 NIH 参考摄入量和可耐受最高摄入量进行比较。服务还会报告 NIH 资料表中提到的药物相互作用、存在 NIH 安全性警示的草药，以及 FDA 召回和不良事件报告。每个回答都会以通俗易懂的摘要开头，便于助手转述（英语或西班牙语）；每个数字都可追溯到对应的标签或 NIH 来源。

该服务在 Pocket Network Beta TestNet 上以付费服务 dietary-supplement-analysis 运行，也作为远程 MCP 服务提供免费试用。

网站	agents.trackmysupplement.com：提供各大 Agent 客户端的连接按钮、实时演示、定价和状态信息。Agent 可查看 llms.txt、agents.md 和 status.json
试用	评审专用：一分钟试用
Pocket Network	Beta TestNet 上的服务 ID 为 dietary-supplement-analysis，中继端点为 https://pokt-beta.trackmysupplement.com。通过 Pocket 门户的全部 9 项验收规则，并已结算付费中继的链上交易（记录）
MCP 服务	https://agents.trackmysupplement.com/mcp，已列入 MCP 官方注册表 和 Smithery。详见 mcp/README.md
准确性	62 个人工处理的案例，全部通过（EVAL.md）
运行版本	/v1/version；每个版本发布记录均列于 CHANGELOG.md
运行供应商或网关	OPERATORS.md：每次发布都会提供多架构镜像

数据来源，均为公开数据：

• 标签：NIH 膳食补充剂标签数据库（DSLD），API v9，加上每周同步的 NIH 完整下载数据镜像（214,782 个标签）。
• **参考值：**食品与营养委员会的膳食参考摄入量（DRI），由 NIH 膳食补充剂办公室资料表发布。
• **相互作用和草药：**NIH ODS 和 NCCIH 资料表；药物名称使用 NIH RxNorm 进行规范化。
• 召回和不良事件：openFDA。
• **食物：**USDA SR28（FoodData Central 的“SR Legacy”）；美国典型摄入量数据来自 What We Eat in America、NHANES 2017–March 2020。

**本服务不提供：**医疗建议或诊断。它会报告标签声明的内容，将总量与已发布的参考值进行比较，并转述 NIH 发布的相互作用和安全性说明。相互作用列表并不完整；没有标记仅表示未发现可报告的内容，并不代表一切安全。

评审专用：一分钟试用

服务 ID	dietary-supplement-analysis（Pocket Network Beta TestNet，rpc_type: REST，每次中继 500 个计算单位）
中继端点（已质押的供应商）	https://pokt-beta.trackmysupplement.com。仅接受已签名的 Pocket 中继请求。
演示端点（直接访问，免费试用）	https://agents.trackmysupplement.com。使用相同的后端，但不经过中继层，因此可使用 curl。每个客户端每分钟最多 30 个请求，每天最多 100 次调用（详情）；超出限制时会返回 429，并包含 "code":"RATE_LIMITED" 和 Retry-After 标头。
付费 Agent 通过 Pocket Network 调用服务：在 Beta 上为 dietary-supplement-analysis 质押一个应用，并按通过 Pocket Network 中的说明使用 pocket-ap 中继。无论采用哪种方式，以下路径和请求正文都相同；演示端点只是跳过中继层，因此你可以使用 curl，无需质押。

每个示例都是一次调用，调用方式与助手在用户用日常语言描述自己的习惯后所采用的方式相同。jq -r .agent_summary 会输出助手转述的答案；每个示例下方都展示了实时答案的精简版本。

1. “我 74 岁，正在服用 Coumadin。我服用 Centrum Silver、鱼油和银杏。”

curl -s https://agents.trackmysupplement.com/v1/stack/analyze -H 'Content-Type: application/json' -d '{
  "age": 74, "sex": "female", "detail": "summary", "medications": ["Coumadin"],
  "products": [{"query": "Centrum Silver Women 50+"}, {"query": "Nature Made Fish Oil 1200 mg"}, {"query": "Ginkgo Biloba 120 mg"}]}' | jq -r .agent_summary

银杏（Nutricost Ginkgo Biloba 120 mg 中的成分）：NCCIH：银杏可能会增加服用华法林等抗凝药者的出血风险。此组合中的维生素 K 与 Coumadin：维生素 K 会抵消华法林的作用；NIH 将其描述为严重且可能危险的相互作用。此组合中的维生素 E 与 Coumadin：……此组合中的 EPA/DHA 与 Coumadin：高剂量鱼油可能延长凝血时间并升高 INR……在 interactions.findings 中还有 1 条相互作用结果。

系统会将品牌名识别为华法林，在 NIH 标签数据库中按名称找到三种产品，并且每条警告都引用其 NIH 或 NCCIH 资料页。

2. “我怀孕了。我服用孕妇复合维生素、25,000 IU 维生素 A（用于改善皮肤），以及缓解压力的南非醉茄。”

curl -s https://agents.trackmysupplement.com/v1/stack/analyze -H 'Content-Type: application/json' -d '{
  "age": 29, "sex": "female", "life_stage": "pregnancy", "detail": "summary",
  "products": [{"query": "Nature Made Prenatal Multi + DHA"}, {"query": "vitamin A 25000 IU"}, {"query": "ashwagandha root extract"}]}' | jq -r .agent_summary

维生素 A：每日 7500 mcg，而 UL 为 3000 mcg（250%）……UL 可防止肝损伤，以及怀孕期间服用时的出生缺陷（仅适用于预形成维生素 A）。去掉……25,000 IU 维生素 A 会使维生素 A 降至 0 mcg。南非醉茄：……NCCIH：怀孕和哺乳期间应避免服用南非醉茄。

3. “我 62 岁：Centrum Silver、鱼油、镁和锌。我应该再补充 5000 IU 维生素 D 吗？” 使用 "diet": "typical" 时，也会计入食物中的营养素。

curl -s https://agents.trackmysupplement.com/v1/stack/analyze -H 'Content-Type: application/json' -d '{
  "age": 62, "sex": "female", "diet": "typical",
  "products": [{"query": "Centrum Silver Women 50+"}, {"query": "Nature Made Ultra Fish Oil 1400"},
               {"query": "KAL Magnesium Glycinate 400"}, {"query": "Thompson Zinc 50 mg", "servings_per_day": 1}],
  "candidates": [{"query": "vitamin d3 5000 iu"}]}' | jq -r .agent_summary

锌：每日 65 mg，而 UL 为 40 mg（163%），主要来自 Thompson Zinc 50 mg。UL 可防止铜营养状况降低……镁：每日 500 mg，而 UL 为 350 mg（143%）……去掉 Thompson Zinc 50 mg 后，锌会降至 15 mg（UL 的 37.5%）。……添加……Vitamin D3 5000 IU 会使维生素 D 超过上限（达到 UL 的 150%）。

答案会给出能够解决问题的一项调整，而假设分析也会回答用户实际提出的问题。

4. 用西班牙语：“我服用 Centrum Silver 和 Caltrate；我正在服用华法林和左甲状腺素。”

curl -s https://agents.trackmysupplement.com/v1/stack/analyze -H 'Content-Type: application/json' -d '{
  "age": 68, "sex": "female", "lang": "es", "detail": "summary", "medications": ["warfarina", "levotiroxina"],
  "products": [{"query": "Centrum Silver Women 50+"}, {"query": "Caltrate 600+D3"}]}' | jq -r .agent_summary

此组合中的维生素 K 与华法林：维生素 K 会抵消华法林的作用……此组合中的钙与左甲状腺素：……服用碳酸钙后 4 小时内不要服用左甲状腺素。此组合中的铁与左甲状腺素：……

**5. 扫描瓶身：**扫描条形码即可找到标签；同一条形码也可查找 FDA 召回信息和不良事件报告。

curl -s https://agents.trackmysupplement.com/v1/products/lookup -H 'Content-Type: application/json' -d '{"upc":"031604026974"}' | jq -r '.product.brand + " " + .product.name'
curl -s https://agents.trackmysupplement.com/v1/products/fda -H 'Content-Type: application/json' -d '{"upc":"031604026974"}' | jq -r .agent_summary

对于有召回记录的产品，试试 {"query":"Nature Made Vitamin D3 1000 IU"}：FDA 列出了 4 条匹配的召回信息。

**6. Agent 与 Agent 协作：**预计大量使用场景会来自其他 Agent 执行更大的任务，整个过程中无需用户输入：药房 Agent 将新处方与档案中的补充剂进行核对，购物 Agent 在结账前检查购物车，视觉 Agent 传递从照片中读取的标签，健康指导 Agent 进行每周检查，以及用药审查 Agent 将此服务与药物相互作用服务结合使用。examples/ 提供了这五种场景的单个脚本（bash examples/agent-flows.sh），以及一个 50 行的助手，它会从 GET /v1/tools 加载工具，并允许模型调用这些工具（agent_loop.py）。

更多调用：POST /v1/nutrients/reference（离线查询单种营养素的 RDA 和 UL）、POST /v1/products/search（查找标签）、POST /v1/interactions/check（不带补充剂组合检查药物），以及供 Agent 框架使用的 GET /v1/tools、GET /v1/guide 和 GET /openapi.json。这些接口都列在端点下。

通过 Pocket Network（付费中继）

你需要在 Beta TestNet 上为 dietary-supplement-analysis 质押一个应用。从 Beta 水龙头 为一个地址注资，并将其作为应用质押至少 1,000 POKT。然后安装 pocket-ap，并使用此仓库的客户端配置进行中继：

export POCKET_APP_PRIVATE_KEY=<your app key, 64 hex>   # pocketd keys export <name> --unarmored-hex --unsafe
pocket-ap call --config deploy/beta-stake/pocket-ap.yaml \
  --service dietary-supplement-analysis --rpc-type rest \
  -X POST --path /v1/stack/analyze \
  -d '{"age":34,"sex":"female","products":[{"name":"Custom magnesium","ingredients":[{"name":"magnesium","amount":250,"unit":"mg"}]}]}' -v

链上记录（Beta TestNet）

步骤	交易哈希	区块
服务已注册，使用 card/card.json 中的卡片	BC01B11F…7DD5	722359
服务提供方已质押 60,000 POKT	9CBCBAAF…51FA	722747
测试应用已质押 1,100 POKT	6734D5F4…05EE	722744
首次付费中继的声明（在区块 722813 结算）	F3D81B3F…88EB	722793
使用 pocket-ap，于 2026-10-11 从所有者的 Mac 发送的 judges' example A（v0.12.6）中继声明（已结算；从应用质押中扣除 500 个计算单位）	A9A5B384…3DA5	724433

详情和服务端设置见 deploy/PHASE4_READINESS.md。

为什么这对 Pocket Network 很重要

• 数百万人都会问的问题。 60.2% 的美国成年人在过去 30 天内服用过膳食补充剂，38.7% 服用过两种或以上，75.9% 的 60 岁及以上成年人至少服用过一种（CDC NCHS，2021–2023）。健康、药房、杂货和健身助手都会被问到某种服用方案是否合适；要给出可靠答案，需要知道每个标签上的确切剂量，以及适用于该个人的 NIH 限值，而这些信息不是模型本身就具备的。
• 重复调用，其中许多来自其他 Agent。 每次调用都是一次中继（500 个计算单位）。药房、购物、辅导和用药审查 Agent 会在每次收到新处方、购物车、照片或每周检查时调用它，无需有人介入（示例）。
• 补足 Pocket 自有健康服务的空缺。 Pocket 的目录中有药物服务（fda、med-safety、clinical-trials），但没有补充剂服务，而这些服务的大多数用户也会服用补充剂。已经为处方调用那些服务的 Agent，可以调用此服务来处理药柜中的其他所有东西。
• 从免费试用转向付费中继。 MCP 服务已列入官方 MCP Registry、Smithery 和 mcpservers.org。免费试用（每个连接每天 25 次检查）足以让个人用户试用；每条限额提示都会引导有实际用量的 Agent 使用 Pocket 路由，该路由永不计量。
• 已准备好迎接更多服务提供方。 每个版本都会发布多架构镜像，OPERATORS.md 可在大约 5 分钟内完成服务提供方设置，并且响应从不使用 5xx，因此网关不会把错误输入误判为服务提供方故障。
• 经过验证。 每个版本都会通过 62 个手工测试用例（EVAL.md），并按 30 分钟的计划，针对公共端点和 Pocket 门户审计测试线上服务。

端点

所有输入均来自 JSON 请求正文。所有响应均为 JSON 对象，包括错误响应。

方法	路径	用途
GET/HEAD	/	服务标识
GET	/v1/version	{"service":"dietary-supplement-analysis","version":"0.15.1"}
GET	/v1/health	{"status":"ok"}
GET	/openapi.json	OpenAPI 3.1 规范（也可见于 openapi/openapi.json）
POST	/mcp	远程 MCP 服务（Streamable HTTP，无状态）：向 MCP 客户端提供相同的工具
GET	/v1/provenance	代码版本、Git 提交记录及各数据源的版本
GET	/v1/tools	用于函数调用的工具定义（name、description、JSON Schema input_schema）
GET	/v1/guide	提供给 Agent 的使用指南，以 JSON 中的 Markdown 格式呈现（文本与 llms.txt 相同）
POST	/v1/stack/analyze	一次调用：汇总 1–15 种产品的各营养素总量（名称、条形码、ID 或自定义产品），并提供标记、修正建议和假设情景候选项
POST	/v1/interactions/check	查询 NIH 列出的药物或健康状况相关营养素相互作用，无需提供营养补充组合：{"medications":["Synthroid"],"nutrients":["calcium"]}
POST	/v1/products/search	在 DSLD 中查找产品：{"query":"vitamin d3 5000","brand":"NOW","limit":5}；合并标签版本
POST	/v1/products/lookup	查询条形码对应的标签：{"upc":"031604026974"}
POST	/v1/products/fda	查询某款产品的 FDA 召回和不良事件报告（openFDA）：{"query":"Nature Made D3 1000 IU"}、{"upc":...}、{"dsld_id":...} 或 {"brand":...,"name":...}
POST	/v1/products/get	获取标准化标签：{"dsld_id":12345} 或 {"dsld_ids":[...]}（最多 10 个）
POST	/v1/nutrients/reference	查询单种营养素的 RDA/EAR/AI/UL 和 UL 依据：{"nutrient":"vitamin d","age":34,"sex":"female"}（离线）
POST	/v1/tool	MCP 风格的分发器：{"tool":"stack_analyze","arguments":{...}}

POST /v1/stack/analyze

{
  "age": 34,
  "sex": "female",
  "products": [
    { "query": "Centrum Silver Women 50+" },
    { "upc": "031604026974", "servings_per_day": 1 },
    { "dsld_id": 67890 },
    { "name": "Homemade magnesium", "ingredients": [ { "name": "magnesium glycinate", "amount": 200, "unit": "mg", "nutrient_basis": "elemental" } ] }
  ],
  "medications": [ "warfarin", "Synthroid 50 mcg" ],
  "conditions": [ "smoker" ],
  "candidates": [ { "query": "vitamin d3 5000 iu" } ]
}

• 产品（1–15）可以是产品名称（query，可选填 brand）、条形码（upc）、DSLD ID，或明确列出成分的自定义产品。自定义成分可以指定 form（例如 "folic acid" 或 "d-alpha tocopherol"），以便进行 IU 和 DFE 换算。

• 名称和条形码会在服务端解析。名称会根据其词语在品牌和产品名称中的匹配比例，与 DSLD 搜索结果进行匹配；同一产品的不同标签版本会合并，并采用最新的在售版本。resolutions[] 会记录每个匹配项及其 confidence（high：每个词都匹配到同一产品；medium：每个词都匹配到产品，但也匹配到其他产品，或大多数词都匹配；low：匹配率低于 60%），以及最多三个备选项。无法识别的产品会予以报告（PRODUCT_NOT_RESOLVED）并从结果中排除；只有在没有任何产品可识别时，调用才会返回 404。

• diet: "typical" 会添加该年龄和性别人群从食物和饮料中摄入的美国日均量（What We Eat in America，NHANES 2017–March 2020），并在 with_typical_diet 中重复相关比较。只有当 UL 涵盖食物来源时，食物摄入量才计入 UL：总摄入量 UL 会计入全部食物，叶酸会计入食物中的叶酸，维生素 A 会计入视黄醇，维生素 E 会计入添加的维生素 E，镁则不计入食物来源。此项不适用于 2 岁以下人群及孕期和哺乳期。

• medications（最多 30 种，可按用户提供的通用名或品牌名填写）会与 46 个药物类别进行匹配，并检查 NIH 膳食补充剂办公室情况说明书中列出的 55 种药物相互作用（data/interactions.json）。对于列表不认识的名称，如果服务能够访问 NIH RxNorm（RxNav），就会将其规范化为对应成分；匹配采用完整词匹配，不使用模糊匹配。interactions.findings[] 会列出每种相互作用的类型（supplement_changes_drug、drug_lowers_nutrient、drug_raises_nutrient、additive_risk、two_way）、NIH 提供的用药时间建议、情况说明书，以及包含相关产品的 in_stack；堆栈内的相互作用会优先列出，并置于 agent_summary 的开头。该列表并不完整（INTERACTIONS_PARTIAL），且绝不会记录药物名称。

• 植物成分。 对具有 NIH 安全性警示的草药及其他非营养成分（目前共 24 种：南非醉茄、卡瓦胡椒、圣约翰草、银杏、绿茶提取物、姜黄／姜黄素、黑升麻、藤黄果、红曲米、黄连、黄连素、育亨宾、麻黄、缬草、紫锥菊、大蒜、亚洲人参、锯棕榈、水飞蓟、甘草根、苦橙、葫芦巴、肉桂、肌酸），会在 botanicals[] 中报告 NCCIH 或 ODS 的说明、孕期说明，以及 NIH 提到剂量时的剂量检查（肌酸每日超过 5 g 和 25 g、EGCG 每日 843 mg、缬草每日超过 600 mg）。匹配依据是 DSLD 的成分分组，或去除植物部位和制备方式词语后的确切名称（“Ashwagandha Root Extract”会匹配南非醉茄），不会使用子字符串匹配；单独的“ginseng”（可能指西洋参或西伯利亚人参）、单独的“cassia”（也指另一种植物属）以及 DGL 甘草均不会匹配（data/botanicals.json）。填写 medications 时，NIH 指明的植物成分与药物配对（圣约翰草与避孕药、华法林或 SSRIs；银杏与抗凝药；卡瓦胡椒和缬草与镇静药；红曲米与他汀类药物；黄连与二甲双胍；大蒜与抗凝药；亚洲人参和肉桂与糖尿病药物；甘草与皮质类固醇）会成为相互作用发现项。

• conditions：smoker（当前或曾经吸烟，或接触过石棉：每日 β-胡萝卜素达到 20 mg 时会提示，并计入标示为 β-胡萝卜素的维生素 A）、kidney_disease（钾、镁、磷）、hemochromatosis（铁；维生素 C 从 500 mg 起）、lab_test_soon（生物素达到 1 mg 时会干扰甲状腺、肌钙蛋白及其他检测）、cancer_treatment（大剂量维生素 C 和 E）。

• foods（最多 30 项）列出此人一天内吃的食物：{"query": "spinach cooked", "amount": 1, "unit": "cup"}、{"query": "whole milk", "grams": 488} 或 {"ndb_number": "11458", "grams": 180}。食物会根据完整词匹配方式和 USDA 家庭份量，离线与 USDA SR28 的 8,789 种食物（FoodData Central 的 “SR Legacy”）进行匹配，并添加到 nutrient_totals[].with_foods 的补充剂总量中。只有食物提供的营养素会在 foods.totals 中检查。只有当 UL 涵盖食物来源时，食物摄入量才计入 UL，与 diet 的处理方式相同。USDA 未分析的食物营养素会列出，而不会假定为零；SR28 中三个数量级异常的锰数值会被排除并报告。请使用 foods 或 diet: "typical"，不要同时使用。

• timing 会列出适用于该堆栈的 NIH 时间建议，每项均注明相关产品和情况说明书：钙每次服用 500 mg 或以下、碳酸钙随餐服用、钙和铁补充剂分开服用、铁达到 25 mg 或以上时与锌分开服用、大剂量铁随餐服用、维生素 D 与一些脂肪同服、绿茶提取物随餐服用，以及堆栈内相互作用所涉及的药物间隔服用建议。第一项也会出现在 agent_summary 中。

• lang: "es" 会使 agent_summary 使用西班牙语，并将英文文本保留在 agent_summary_en 中。摘要中可能出现的所有 NIH 短语都有经过审校的西班牙语译文（data/i18n-es.json）；其他字段仍使用英文。药物名称可以使用西班牙语名称（warfarina、levotiroxina、omeprazol），也可以使用西班牙语或拉丁美洲品牌名（Sintrom、Eutirox），可带或不带重音符号。

• detail: "summary" 只返回 Agent 回答所需的内容（agent_summary、标记的营养素、建议、resolutions、候选产品判断、data_gap_codes、provenance），通常为 1–3 KB，而非 20–40 KB。

• 候选产品（最多 5 项）是用户正在考虑的产品。每项都会作为堆栈的新增产品在 candidate_results[] 中进行评估，但不会计入总量。

• servings_per_day 默认为标签注明的每日最大份数；若标签未注明，则默认为 1。所有默认值都会列在 assumptions 中。

• age 和 sex 为可选项。不填写时会返回总量和重叠项，但不会进行参考值比较。

• life_stage（"pregnancy" 或 "lactation"；女性，年龄 14–50 岁）会切换为孕期或哺乳期参考值；"pregnant": true 和 "breastfeeding": true 也可以使用。对于婴儿，请将年龄以年为单位的小数形式填写（0.25 表示 3 个月）：对应值适用范围为 0–6 个月和 7–12 个月。 响应依次包含：profile、summary、agent_summary、resolutions（提供了名称或条形码时）、assumptions、suggestions、candidate_results（提供了候选项时）、botanicals（堆栈中含有带 NIH 信号的成分时）、interactions（提供了药物或健康状况时）、nutrient_totals、overlaps、unrecognized_ingredients、data_gaps、products、sources 和 disclaimer。

• agent_summary 为两到五句纯文本，由下方数据确定性生成，Agent 可直接转述。

• suggestions 针对每种超过 UL 的营养素，最多列出三项单产品调整（reduce_servings 或 remove_product），并说明调整后的含量、该调整是否足以使含量降至 UL 或以下（resolves）、还会同时解决哪些其他超 UL 营养素，以及移除产品还会降低哪些其他营养素的含量。这些只是算术结果，不构成建议。

• candidate_results 为每个候选项列出 verdict（adds_above_ul、increases_above_ul、adds_near_ul 或 no_new_flags）、新增标记，以及调整前后的总量。

每种营养素的总量包含：

字段	含义
daily_total	所有产品中该营养素的总量，使用该营养素的规范单位（mcg RAE、mcg DFE、mg、mcg）
complete	当部分标签条目无法计入时为 false（参见 data_gaps）；此时总量为下限
reference	个人资料对应的 RDA、EAR、AI 和 UL，以及 ul_scope、ul_note 和 ul_basis（UL 防范的情况，例如锌对应的“铜含量降低”）
amount_toward_ul	计入 UL 的部分：叶酸仅计叶酸，维生素 A 仅计预成型维生素 A
percent_of_ul、percent_of_rda、percent_of_ai	分别占各参考值的百分比。当 UL 计入部分仅部分已知且尚未超过 UL 时，不提供 percent_of_ul
coverage	这些补充剂单独提供的 RDA（或 AI）百分比。仅供参考：饮食通常也会提供其中的大部分，因此覆盖率低并不代表摄入不足
flags	above_ul（超过 UL）或 near_ul（达到 UL 的 90–100%）。没有标记表示无需报告，并非对该堆栈的评价
severity	high（达到 UL 的两倍或以上）、moderate（超过 UL）、low（接近 UL）或 null
contributions	每种产品的标签含量、换算后含量、每日服用份数和每日含量
with_typical_diet	使用 "diet": "typical" 时，包含 food、estimated_total、amount_toward_ul、percent_of_ul、coverage 和 flags，其中已计入美国平均食物摄入量

错误

{ "error": { "code": "INVALID_INPUT", "message": "products: ...", "retryable": false, "field": "products" } }

代码	状态	适用情况
INVALID_INPUT	400	输入格式错误或超出范围
NOT_FOUND	404	未知 DSLD ID、营养素或途径
UNSUPPORTED	422	年龄不在 14–50 岁范围内的妊娠或哺乳情况
UPSTREAM_UNAVAILABLE	424	无法访问 DSLD，且没有缓存内容（retryable: true）
INTERNAL_ERROR	422	意外故障。由于 Pocket 网关会将 5xx 视为供应方故障，因此以 4xx 返回

数据缺口代码

代码	含义
BLEND_UNQUANTIFIED	专有混合物列出了成分，但未注明各成分的含量；混合物总重量不会分摊到各成分上
QUANTITY_MISSING	已识别的营养素行没有含量
UNIT_NOT_CONVERTIBLE	单位无法明确换算，例如维生素 A 以 IU 表示，但形式未知
COMPOUND_WEIGHT	该含量可能是化合物重量，而非元素矿物质的重量
AMBIGUOUS_BASIS	以化合物命名的自定义成分缺少 nutrient_basis
UL_PARTIAL	UL 仅适用于一种形式（叶酸、预成型维生素 A），且部分形式未注明
PROFILE_MISSING	缺少年龄和性别，因此无法进行参考值比较
PRODUCT_NOT_RESOLVED	产品名称或条形码无法与 DSLD 标签匹配；该产品不会计入
DATA_SUSPECT	NIH 的标签记录看起来不一致；该含量仍会计入。check 会说明未通过哪项测试：duplicate_row（同一成分在同一标题下出现两次，例如将 EPA 作为 DHA 输入）、nested_exceeds_parent（各行合计超过其声明的总量）、percent_dv_mismatch（无论按当前还是 2016 年前的每日参考值计算，标示的 %DV 都与含量不符）、implausible_amount（超过成人最高 UL 的 50 倍，通常是将 mg 错输为 mcg）
INTERACTIONS_NOT_ASSESSED	未提供 medications，因此未检查药物相互作用。绝不会评估补充剂之间的相互作用
INTERACTIONS_PARTIAL	已检查药物，但仅针对 NIH ODS 资料表中列出的相互作用；列表并不完整
FOOD_NOT_RESOLVED	foods 中的食物与 USDA SR28 中的任何食物都不匹配，因此不会计入
FOOD_PORTION_UNKNOWN	USDA 未列出该食物所给单位对应的份量；列出的份量位于 foods.items[].portions 中（请改用克数）
FDA_UNAVAILABLE	仅适用于 /v1/products/fda：无法连接 openFDA 查询召回或不良事件；答案的其余部分仍然有效
MEDICATION_NOT_RECOGNIZED	药物名称无法与 NIH 资料表相互作用列表中的任何类别匹配（直接匹配或通过 RxNorm 匹配），因此未进行任何检查

数字的生成方式

准确性通过 62 个手工处理的案例进行检查；请参阅 EVAL.md。

• 读取 DSLD 标签：
  • DSLD 通常将维生素 A 记为普通 mcg 或 mg。只有当标签上的 %DV 与 900 mcg RAE 的每日摄入量相符时，才会将其读取为 mcg RAE。
  • 当 DSLD 未标明单位时（例如“6 NP”），只有在标签上的 %DV 与 FDA 每日摄入量相符时才会推断单位；否则视为数据缺失。
  • 嵌套在某种营养素下的行会按形式细分该营养素（叶酸 800 mcg DFE = 叶酸 480 mcg）。这些行提供 UL 的确切组成部分，绝不会重复计数。
  • 明确标注的形式占比（“40% as beta-carotene”）在覆盖 100% 时会精确拆分 IU 换算值。覆盖不足时，剩余部分会视为未知形式。
  • Gamma 和 delta 生育酚以及生育三烯酚不计入维生素 E。
• 匹配成分与营养素时，会依次尝试：DSLD 的 ingredientGroup、UNII 代码、完全匹配的同义词，然后是恰好属于一种营养素的精确形式名称。不进行子串或模糊匹配，因此“Vitamin B”绝不会匹配“Vitamin B12”。其他成分均归入 unrecognized_ingredients。
• 单位换算仅在结果明确无歧义时进行：
  • 维生素 D：1 mcg = 40 IU。
  • 维生素 E：天然形式每 IU 为 0.67 mg，合成形式每 IU 为 0.45 mg。形式未知时视为数据缺失。
  • 维生素 A：只有视黄醇或补充剂中的 β-胡萝卜素才会将 IU 换算为 mcg RAE（每 IU 为 0.3 mcg RAE）。
  • 叶酸：普通 mcg 的叶酸 × 1.7 = mcg DFE。
  • %DV 会按标签原样显示，绝不会用于总量计算。
• UL 适用范围按每种营养素存储，并在响应中说明：
  • 镁：仅限补充剂和药物。
  • 叶酸：仅限叶酸。
  • 维生素 A：仅限预成型维生素 A。
  • 烟酸和维生素 E：仅限补充剂摄入量。
  • 其他所有营养素：UL 适用于总摄入量。某种补充剂的总量低于这类 UL，并不能说明总摄入量也低于 UL；assumptions 会对此作出说明。
• 参考数据位于 data/source/manual.json 中。scripts/build-nutrients.ts 会据此生成 data/nutrients.json，并在存在 SuppleTracker global_compounds 导出文件时，也会使用该文件。构建过程会验证单位、来源、年龄范围和同义词冲突。数据涵盖 26 种具有 DRI 的维生素和矿物质，以及 EPA、DHA、褪黑素、CoQ10 和 β-胡萝卜素；这些成分可被识别，但没有参考值。

在本地运行

npm ci
npm run dev                   # http://localhost:8080 (live DSLD)
DSLD_FIXTURES_DIR=test/fixtures/dsld npm run dev   # offline, synthetic fixture labels 900001-900005
npm run check                 # data + OpenAPI freshness, lint, typecheck, tests
docker compose up --build     # container on 127.0.0.1:8080

环境变量	默认值	用途
PORT / HOST	8080 / 0.0.0.0	监听地址
DSLD_API_KEY	无	api.data.gov 密钥，以 X-Api-Key 的形式发送给 DSLD（将 NIH 的限额从每小时 1,000 次请求提高到 10,000 次）
OPENFDA_API_KEY	无	用于 openFDA 的同一个 api.data.gov 密钥
OPENFDA / RXNORM	开启	设为 off 可停止调用 openFDA 或 RxNorm（此时药物匹配只使用 data/interactions.json 中的名称）
FREE_TIER_HOSTS	无	可享受免费试用配额的主机名（演示使用 agents.trackmysupplement.com）；其他主机（例如 Pocket 中继）的请求不会计入配额。FREE_TIER_PER_SESSION、FREE_TIER_PER_IP、FREE_TIER_PER_IP_MCP 和 FREE_TIER_GLOBAL 用于调整配额
DSLD_BASE_URL	https://api.ods.od.nih.gov/dsld/v9	DSLD API 基础 URL
DSLD_PREWARM_IDS	无	启动时缓存的标签 ID，以逗号分隔
DSLD_STORE_PATH	容器中为 /data/dsld.sqlite，否则关闭	持久化标签存储（SQLite）。每个获取的标签都会保留；当 NIH 无法访问时，可从中返回标签、条形码和搜索结果。设为空可关闭
DSLD_WARM	1	启用存储后，后台任务会以每秒约一次请求的速度将热门产品写入存储（查询见 data/warm-queries.json）。设为 0 可关闭
DSLD_FIXTURES_DIR	无	使用本地 label-<id>.json 文件提供 DSLD 数据（仅用于开发；test/fixtures/dsld/real 中有 12 个真实标签）
UPSTREAM_BUDGET_MS	8000	单个请求等待 DSLD 的总时长上限，超时后返回 424
LOG_LEVEL	info	日志仅记录方法、路径、状态和耗时，绝不记录请求正文

限制

• 每次 analyze 调用最多处理 15 种产品和 5 个候选项，每次 get 调用最多处理 10 个 ID，搜索结果最多 10 条。
• **NIH 的完整 DSLD 下载数据（214,782 个标签）已镜像到标签存储中，并会在 NIH 发布新版时每周刷新。**镜像中的标签和条形码查询无需调用 NIH。名称搜索使用实时 API（需要 api.data.gov 密钥），并以镜像作为后备；每当 NIH 限流时，系统会自动切换到镜像，持续 10 分钟。GET /v1/provenance 会显示镜像版本。
• DSLD 调用最多同时运行 4 个，每个调用的截止时间为 6 s，每个请求的预算为 8 s。标签在内存中缓存 7 天，搜索结果缓存 24 小时；标签也会保存在持久标签存储中（每 30 天刷新）。如果 DSLD 不可用，系统会改用过期副本和标签存储提供响应；来自存储的搜索结果会注明 "search_source": "local"。与实时 DSLD 相比，实测冷启动时分析 15 种产品需要 1.5 s，热启动时需要 17 ms。
• 对 Pocket 网关而言会被视为错误信号的文本（例如 "timeout"、"block not found" 等）会在响应中进行 \u 转义。解码后仍是相同的字符串。
• 年龄范围为出生至 120 岁，另包括孕期和哺乳期（14–50 岁）。咖啡因会参照 FDA 指引进行检查（健康成人每天 400 mg，孕期低于 200 mg），钠会参照 2019 年慢性病风险降低摄入量（2,300 mg）进行检查；二者都不是 DRI UL，响应会在 ul_note 中说明这一点。
• **公共演示端点提供免费试用。**每个客户端每分钟最多可发起 30 个请求，此外还有每日配额，并于 00:00 UTC 重置：
  • 每个 MCP 连接最多调用工具 25 次（每个连接有独立的 Mcp-Session-Id），每分钟最多 20 次；
  • 每个 IP 最多调用 REST 100 次；
  • 每个 IP 最多调用 MCP 1,000 次（claude.ai 等托管客户端会共用出口地址）；
  • 总计 5,000 次免费调用。 发现操作（GET 路由、initialize、tools/list）免费。结果质量不会降低。REST 响应会携带 X-Free-Tier-Remaining、X-Free-Tier-Limit 和 X-Free-Tier-Reset 标头；MCP 结果会在 _meta.free_tier 中携带相同信息。超出配额后，REST 会返回 429 RATE_LIMITED；MCP 会返回易于理解的工具结果，说明配额重置时间以及如何切换到付费 Pocket 路由。
  • 计数器使用加盐哈希，并保留两天。
  • 通过 Pocket Network 中继的请求永不计入用量。

免责声明、条款和许可证

**仅供参考，不构成医疗建议。**本服务会报告补充剂标签上的声明内容，以及相关总量与 NIH 和 FDA 发布的参考值、相互作用和安全性说明之间的对比。它不提供诊断或治疗建议，不能替代医生或药剂师的意见，也不用于诊断、治疗、治愈或预防任何疾病。标签和公开数据可能有误或已过时；相互作用列表仅涵盖 NIH 列出的内容；没有标记不代表完全安全。开始、停止或更改补充剂或药物之前，请咨询医疗专业人员；如遇紧急情况，请拨打 911 或联系 Poison Control（美国：1-800-222-1222）。每条响应都会在 disclaimer 字段及 agent_summary 的最后一句中附上此免责声明；转发结果的应用和 Agent 同意一并转发。

使用托管服务须遵守使用条款。NIH、FDA 和 USDA 均未认可本服务；品牌名称仅用于识别产品。

代码采用 MIT 许可证。本服务使用的 DSLD、ODS、NCCIH、RxNorm、openFDA 和 USDA 数据均为美国政府作品，属于公有领域；data/ 中整理的相互作用和草药文件注明了其 NIH 来源。