Hormonaly Clinical Intelligence

Hormonaly — 公共 API 与集成参考

面向肽类、激素和长寿医学的 AI 原生基础设施。

本仓库是面向企业合作伙伴和 API 集成者的公开集成参考。MCP 服务源代码已发布在本仓库的 Hormonaly-ai/hormonaly-public 中。如需临床服务，请访问 hormonaly.ai。

---

目录

1. 平台概览
2. 架构概览
3. 合作伙伴 API 参考
4. MCP 服务 — 工具架构
5. 身份验证
6. 速率限制与配额
7. 错误与状态码
8. 订阅层级
9. Scribe API
10. 安全与合规
11. 获取访问权限
12. 三透镜评分
13. Webhook 事件
14. API 版本管理与稳定性
15. Hormonaly-1 大模型
16. 关于 Hormonaly

平台概览

Hormonaly 将三大支柱整合到一个平台中：

• 证据综合 — 基于 PubMed 和 594 项精选方案的多 Agent RAG，并采用 GRADE 风格分级（A–D）。每次响应都会查询 6 个生物医学数据库：PubMed、ClinicalTrials.gov、Cochrane、Europe PMC、OpenAlex、Semantic Scholar。
• 临床决策支持 — 基于已核实引文提供实时答复、SOAP/DAP/叙述式记录、相互作用检查、剂量和监测计划。
• 工作流工具 — 为肽类、激素和长寿领域的诊所、配制药房和研究团队提供运营层。

数据一览：

指标	数值
方案	31 个临床类别中的 594 项以上
索引研究	10,000 项以上
AI Agent	42 个专业 Agent 和后台 Agent
设计合作诊所	21 家
接受培训的临床医生	1,000 名以上
国家/地区	5 个
质量流水线检查	每次响应 13 项
引文核实	经 PubMed PMID 验证，超时时间为 4 秒

可通过 API 使用的核心产品：

产品	说明
Helix	临床智能引擎 — 多 Agent RAG、GRADE 评分答复、SSE 流式传输
Scribe	SOAP/DAP/叙述式临床记录生成器，引用均有依据
PharmacyOS	配制药房智能系统 — 方案、相互作用、处方生成
Workspace	完整的多面板临床套件 — 面向企业/合作伙伴的访问权限
MCP Server	@hormonaly/mcp-server — 为 Claude Desktop 和 Agent 框架提供 24 个工具

架构概览

Hormonaly 基于由 42 个 Agent 组成的编排架构构建，分为六类：证据、研究、临床、内容、副驾和提取，另有六个持续运行的后台 Agent。

查询流水线

每次 Helix API 调用都会经过同一条确定性流水线：

Client query
│
▼
NeMo Guardrails (PII redaction · off-topic filter · nvidia/llama-3.1-nemotron-nano-8b-v1)
│
▼
Agent Router (intent classification → tier selection)
│
├── TIER_1_BEST: Claude Sonnet 4.6 → GPT-4o fallback (complex/clinical queries)
├── TIER_2_BALANCED: Claude Sonnet 4.6 → GPT-4o → Claude Haiku 4.5 fallback (Scribe, CDS, Rx)
└── TIER_3_FAST: Claude Haiku 4.5 → GPT-4o Mini → Gemini 2.5 Flash → Claude Sonnet 4.6 fallback (free tier, Three-Lens scoring)
│
▼
Multi-Database RAG Retrieval (6 databases · 80K token cap)
│
▼
Cross-Encoder Reranker (threshold ≥ 0.35, fallback 0.15)
│
▼
NeMo Parse — Full-text PMC enrichment (top 5 citations)
│
▼
Supervisor/Worker agents (complex multi-compound queries)
│
▼
Quality Gate (13 checks · 70% composite threshold · async)
│
▼
Citation Grounding (PMID verification · 4s timeout per citation)
│
▼
NeMo Output Guardrail (dosing safety scan · inline flags)
│
▼
Streaming SSE response → client

Agent 类别

类别	Agent	职责
证据 Agent	主 Agent	搜索 6 个生物医学数据库，为研究发现评级
安全 Agent	主 Agent	筛查相互作用、禁忌症和风险因素
方案 Agent	主 Agent	检索化合物方案和监测要求
矛盾 Agent	主 Agent	呈现意见不一的研究，协调证据立场
临床决策 Agent	主 Agent	综合形成结构化临床建议
质量关卡	主 Agent	对每条响应进行 13 项自动检查
后台 Agent（×6）	自主运行	证据更新、安全监测、知识增强、方案审计、过时检查、用户监测通知——持续运行

模型路由

查询类型	模型	最大令牌数	输出
标准临床	Claude Sonnet 4.6	4,000	流式 SSE + 证据评级 + 引用
复杂（3 种以上化合物 / 30 个以上单词）	Claude Sonnet 4.6	6,000	流式 SSE + 扩展综合分析
证据模式	Claude Sonnet 4.6	6,000	更深入的文献综合分析
扩展思考 / 深度分析	Claude Sonnet 4.6（扩展）	16,000	SSE + 可折叠推理面板
三维评分	Claude Haiku 4.5	600	JSON：长寿 / 健康 / 表现评分 + 结论
多 Agent 主管/工作者	Claude Sonnet 4.6	4,000	SSE + orchestration_steps[]
记录员 / 处方 / 宣传册	Claude Sonnet 4.6	400–4,096	结构化模板（SOAP / DAP / 叙述 / Rx）
免费层级（所有类型）	Claude Haiku 4.5	相同	相同格式；上下文更短，RAG 分块减少
Hormonaly-1（可自托管）	NVIDIA NIM 上的 Hormonaly-1	131k ctx	相同的 SSE 格式；推理时无需依赖第三方

**模型路由说明：**所有层级均使用主模型 + 备用模型链。TIER_1：Claude Sonnet 4.6 → GPT-4o。TIER_2：Claude Sonnet 4.6 → GPT-4o → Claude Haiku 4.5。TIER_3：Claude Haiku 4.5 → GPT-4o Mini → Gemini 2.5 Flash → Claude Sonnet 4.6。NVIDIA NIM（nvidia/llama-3.3-nemotron-super-49b-v1，在 8×H100 SXM 上可自托管）用于引用溯源和 Ask Hormonaly 副驾驶 Agent。Hormonaly-1 是 Hormonaly 专有的微调模型——部署在相同的 H100 基础设施上，并逐步集成，以减少对第三方 API 的依赖。参见 Hormonaly-1 LLM。

证据质量处理流程

• 重排序器 — 对每个 RAG 分块进行交叉编码器评分，阈值 ≥ 0.35（小众化合物的备用阈值为 0.15）
• 令牌上限 — 传递给大模型的 RAG 上下文最多 80,000 个令牌
• 质量关卡 — 针对引用有效性、答案完整性、临床连贯性、安全标记进行 13 项检查——综合评分阈值 ≥ 70%（异步，事后检查）
• 引用溯源 — 使用 4 秒超时，对照 PubMed 验证每个 PMID；未验证的引用将被丢弃
• NeMo Parse — 获取排名前 5 的引用所对应的完整 PMC 文章文本，将其结构化为引言 / 方法 / 结果，并作为增强上下文传入

合作伙伴 API 参考

基础 URL：https://hormonaly.ai/api/v1

身份验证：每个请求均需使用 Authorization: Bearer YOUR_API_KEY。

机器可读的 OpenAPI 规范：GET /api/v1/helix/openapi.json

以下所有端点路径均相对于基础 URL。

Helix 端点

POST /helix/query

提交临床问题，并获取包含证据等级、引文和临床结论的完整 Helix 响应。

请求：

{
  "query": "What is the evidence for BPC-157 in tendon repair?",
  "mode": "evidence",
  "stream": true
}

响应（SSE 流式传输）：

data: {"type":"agent_step","step":"classifying intent"}
data: {"type":"agent_step","step":"searching evidence","sources":26}
data: {"type":"agent_step","step":"verifying citations"}
data: {"type":"content","text":"BPC-157 has demonstrated..."}
data: {"type":"metadata","evidence_grade":"C","confidence":62,"verdict":"CONSIDER","citations":5,"sources_consulted":26}
data: {"type":"done"}

响应元数据字段：

字段	类型	描述
evidence_grade	"A"	"B"
confidence	0–100	综合评分，依据 GRADE、引文密度、人体与临床前证据的比例，以及来源间的一致性计算
citations	number	响应中包含的已验证 PubMed 引文数量
sources_consulted	number	从证据数据库检索到的 RAG 分块数量
agent_type	string	处理该查询的专科 Agent
verdict	"ADOPT"	"CONSIDER"
usage	object	当前已使用的令牌数，占月度预算的比例

GET /helix/protocols/:compound

查询特定化合物的证据质量评级方案。

示例：GET /helix/protocols/bpc-157

响应：

{
  "compound": "bpc-157",
  "evidence_grade": "C",
  "protocols": [
    {
      "indication": "Tendon repair",
      "dose_range": "200–500 mcg/day",
      "route": ["subcutaneous", "intramuscular"],
      "cycle_duration": "4–12 weeks",
      "monitoring": ["liver enzymes at baseline", "symptom review at 4 weeks"]
    }
  ],
  "interactions": [],
  "citations": 5
}

POST /helix/dossier

为某种化合物生成全面的证据档案（异步任务）。需要 Advanced 或 Enterprise 级别。

请求：

{ "compound": "semaglutide", "sections": ["mechanism", "efficacy", "safety", "dosing"] }

响应：{ "job_id": "dossier_abc123", "status": "queued" }

使用 GET /helix/dossier/:job_id 轮询，直到 status: "complete"。

POST /helix/compare

从证据等级、安全性、剂量和临床就绪度等方面，对 2–3 个方案进行正面对比。需要 Advanced 或 Enterprise 级别。

请求：

{ "compounds": ["testosterone-cypionate", "testosterone-enanthate"] }

GET /helix/health

服务健康检查。无需身份验证。

{ "status": "ok", "latency_p50_ms": 4200, "citation_coverage": "99%" }

MCP 服务 — 工具架构

包：@hormonaly/mcp-server

Hormonaly MCP 服务提供 24 种工具，可让 Claude Desktop、Cursor 或任何兼容 MCP 的 Agent 直接查询完整的 Helix 临床智能技术栈——无需在你这边编写 HTTP 客户端代码。

安装（Claude Desktop）

MCP 服务的源代码可在我们的 GitHub 仓库中获取。克隆并在本地构建：

git clone https://github.com/Hormonaly-ai/hormonaly-public.git
cd hormonaly-public/mcp/hormonaly-mcp-server
npm install && npm run build

然后按以下步骤配置 Claude Desktop：

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "hormonaly": {
      "command": "node",
      "args": ["/path/to/hormonaly-mcp-server/dist/index.js"],
      "env": {
        "HORMONALY_API_URL": "https://hormonaly.ai",
        "HORMONALY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

重启 Claude Desktop，即可立即使用这些工具。

HTTP/SSE 模式（适用于服务端 Agent）：

HTTP_PORT=3100 node dist/index.js
# SSE: GET http://localhost:3100/sse?sessionId=YOUR_ID
# POST: POST http://localhost:3100/messages?sessionId=YOUR_ID
# Health: GET http://localhost:3100/health

完整的设置说明请参阅 mcp/README.md。

远程 MCP — Claude.ai 一键连接

已上线 · 发布于 2026 年 5 月 · 注册表：registry.modelcontextprotocol.io

Hormonaly MCP 服务已部署为远程 HTTP/SSE 服务，并列入官方 MCP 注册表，标识为 io.github.Hormonaly-ai/hormonaly。使用 Claude.ai 的企业客户可一键连接——无需本地安装、无需 Docker，也无需编辑 claude_desktop_config.json。

属性	值
SSE 端点	https://mcp.hormonaly.ai/sse
注册表 ID	io.github.Hormonaly-ai/hormonaly
身份验证标头	x-api-key: hk_live_...（合作伙伴 API 密钥）
基础设施	GCP Cloud Run · Cloudflare DNS · 由 GCP 配置 TLS

一键连接流程（Claude.ai Enterprise）

1. Claude.ai 通过 MCP 注册表发现 Hormonaly——无需手动输入 URL
2. 用户点击 Connect——Claude 提示：“请输入你的 x-api-key”
3. 用户粘贴其 hk_live_... 合作伙伴 API 密钥（可从 Partner Portal → API Keys 获取）
4. 对话中立即启用全部 24 种工具

身份验证与访问级别

工具组	是否需要身份验证	示例
方案、证据、化合物工具（9 种工具）	无——公开只读访问	protocol_search、compound_get_dosing（evidence_grade 需要 API 密钥）
Helix 与 Agent 工具（8 种工具）	需要 API 密钥	helix_query、run_clinical_workflow、helix_deep_analysis、evidence_grade
用户工具（4 种工具）	会话令牌	user_get_profile、monitor_protocol_updates
管理工具（3 种工具）	管理员会话	admin_get_stats、admin_list_users

合作伙伴 API 密钥以 hk_live_ 开头，可从 Partner Portal 获取。密钥通过 x-api-key SSE 标头传递——Claude.ai 会在首次连接时提示输入。

完整工具架构

Helix 工具

工具	描述	认证
helix_query	临床问题 → 带引用和置信度评分的循证答案	API key
helix_compare	对 2–3 种化合物进行正面对比（Advanced/Enterprise）	API key
helix_protocol	从 Helix API 获取某种化合物的所有方案	API key
helix_dossier_start	启动异步档案生成任务（Advanced/Enterprise）	API key
helix_dossier_status	按 job_id 轮询档案任务状态	API key
helix_deep_analysis	使用完整 RAG 流程、Three-Lens 评分和 PMID 引用列表进行扩展分析	API key
run_clinical_workflow	用于复杂临床问题的完整 supervisor/worker 多 Agent 工作流	API key

方案工具

工具	描述	认证
protocol_search	按化合物、类别或病症搜索方案库	公开（无需认证）
protocol_get	按 ID 或 slug 获取完整方案详情	公开（无需认证）
protocol_list_categories	列出所有 31+ 个方案类别及其数量	公开（无需认证）
protocol_get_interactions	检查一组化合物之间的相互作用（批量端点需要会话认证）	会话

证据工具

工具	描述	认证
evidence_search	在 PubMed 中搜索有关化合物或病症的研究	公开（无需认证）
evidence_get	按 ID 获取完整证据记录	公开（无需认证）
evidence_grade	使用 GRADE 框架对一组 PMID 引用进行评级 — 为每项研究返回 A/B/C/D 级别及理由	API key

化合物工具

工具	描述	认证
compound_search	按名称或类别搜索化合物数据库	公开（无需认证）
compound_get_interactions	获取某个化合物 slug 对应的所有已知相互作用	公开（无需认证）
compound_get_dosing	获取基于证据的剂量范围、给药途径和周期指导	公开（无需认证）

用户工具（需要会话认证）

工具	描述
user_get_profile	获取当前用户的个人资料
user_get_usage	获取当前用户的 AI 使用统计
user_get_saved_protocols	获取当前用户保存的方案
monitor_protocol_updates	检查已保存方案是否存在证据过时（>90 天）；返回 review_recommended 标记

管理员工具（需要管理员会话）

工具	描述
admin_get_stats	获取全平台统计数据
admin_list_users	列出用户，支持可选搜索和分页
admin_get_ai_costs	按模型和端点获取 AI 成本明细

Agentic 工作流工具

以下三个工具可启用完整的多 Agent 流程：

run_clinical_workflow — Supervisor/worker 模式。将复杂临床问题拆解为 3–4 个并行子任务（证据搜索、相互作用检查、方案查询、临床综合分析），调度专业 Agent，并返回综合报告，其中 orchestration_steps[] 显示每个 Agent 的任务、结果、耗时和置信度。延迟：复杂查询需 30–90 秒。

helix_deep_analysis — 使用完整 RAG 流程进行扩展深度分析。返回三个独立临床视角（Longevity / Health & Disease / Performance）的 Three-Lens 评分、完整 PMID 引用列表、各部分的置信度明细，以及总体证据等级（A–D）。

monitor_protocol_updates — 根据 90 天过时阈值检查已保存的方案。返回 review_recommended 标记，以及每个方案的最新证据更新时间。每周或每月使用一次，以及时了解文献动态。

MCP 工具输入架构

全部 24 个工具架构。Claude Desktop 和 MCP 客户端会使用 inputSchema 块，在发送参数前进行验证。

helix_query

{
  "name": "helix_query",
  "inputSchema": {
    "type": "object",
    "properties": {
      "question": { "type": "string", "description": "Clinical question", "maxLength": 10000 },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "detail_level": { "type": "string", "enum": ["clinical","summary"], "default": "clinical" },
      "include_citations":{ "type": "boolean", "default": true },
      "include_three_lens":{ "type": "boolean", "default": false },
      "api_key": { "type": "string", "description": "Override env API key" }
    },
    "required": ["question"]
  }
}

helix_compare（Advanced/Enterprise）

{
  "name": "helix_compare",
  "inputSchema": {
    "type": "object",
    "properties": {
      "compounds": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 3 },
      "indication": { "type": "string", "default": "General comparison" },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "api_key": { "type": "string" }
    },
    "required": ["compounds"]
  }
}

helix_protocol

{
  "name": "helix_protocol",
  "inputSchema": {
    "type": "object",
    "properties": {
      "compound": { "type": "string", "maxLength": 200 },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "api_key": { "type": "string" }
    },
    "required": ["compound"]
  }
}

helix_dossier_start（Advanced/Enterprise）

{
  "name": "helix_dossier_start",
  "inputSchema": {
    "type": "object",
    "properties": {
      "compound": { "type": "string", "maxLength": 500 },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "api_key": { "type": "string" }
    },
    "required": ["compound"]
  }
}

helix_dossier_status

{
  "name": "helix_dossier_status",
  "inputSchema": {
    "type": "object",
    "properties": {
      "job_id": { "type": "string" },
      "api_key": { "type": "string" }
    },
    "required": ["job_id"]
  }
}

helix_deep_analysis（Enterprise）

{
  "name": "helix_deep_analysis",
  "inputSchema": {
    "type": "object",
    "properties": {
      "topic": { "type": "string", "description": "Clinical topic for deep analysis", "maxLength": 10000 },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "api_key": { "type": "string" }
    },
    "required": ["topic"]
  }
}

run_clinical_workflow

{
  "name": "run_clinical_workflow",
  "inputSchema": {
    "type": "object",
    "properties": {
      "question": { "type": "string", "description": "Complex clinical question", "maxLength": 10000 },
      "patient_context": { "type": "string", "description": "Optional: age, sex, conditions, medications" },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "api_key": { "type": "string" }
    },
    "required": ["question"]
  }
}

monitor_protocol_updates (session auth)

{
  "name": "monitor_protocol_updates",
  "inputSchema": {
    "type": "object",
    "properties": {
      "session_token": { "type": "string" },
      "compound_filter": { "type": "array", "items": { "type": "string" }, "description": "Filter to specific compounds" }
    }
  }
}

protocol_search

{
  "name": "protocol_search",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "category": { "type": "string", "description": "e.g. 'weight-loss', 'hormones'" },
      "limit": { "type": "number", "default": 10 }
    },
    "required": ["query"]
  }
}

protocol_get

{
  "name": "protocol_get",
  "inputSchema": {
    "type": "object",
    "properties": { "id": { "type": "string" } },
    "required": ["id"]
  }
}

protocol_list_categories

{
  "name": "protocol_list_categories",
  "inputSchema": { "type": "object", "properties": {} }
}

protocol_get_interactions

{
  "name": "protocol_get_interactions",
  "inputSchema": {
    "type": "object",
    "properties": {
      "compounds": { "type": "array", "items": { "type": "string" }, "minItems": 2,
      "description": "Compound slugs to screen" }
    },
    "required": ["compounds"]
  }
}

evidence_search

{
  "name": "evidence_search",
  "inputSchema": {
    "type": "object",
    "properties": {
      "compound": { "type": "string" },
      "max_results": { "type": "number", "default": 10 }
    },
    "required": ["compound"]
  }
}

evidence_get

{
  "name": "evidence_get",
  "inputSchema": {
    "type": "object",
    "properties": { "id": { "type": "string" } },
    "required": ["id"]
  }
}

evidence_grade

{
  "name": "evidence_grade",
  "inputSchema": {
    "type": "object",
    "properties": {
      "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20,
      "description": "Evidence record IDs to GRADE-score" },
      "api_key": { "type": "string", "description": "Helix API key" }
    },
    "required": ["ids"]
  }
}

compound_search

{
  "name": "compound_search",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "category": { "type": "string" }
    },
    "required": ["query"]
  }
}

compound_get_interactions

{
  "name": "compound_get_interactions",
  "inputSchema": {
    "type": "object",
    "properties": { "slug": { "type": "string", "description": "e.g. 'semaglutide'" } },
    "required": ["slug"]
  }
}

compound_get_dosing

{
  "name": "compound_get_dosing",
  "inputSchema": {
    "type": "object",
    "properties": { "slug": { "type": "string", "description": "e.g. 'testosterone-cypionate'" } },
    "required": ["slug"]
  }
}

user_get_profile

{
  "name": "user_get_profile",
  "inputSchema": {
    "type": "object",
    "properties": { "session_token": { "type": "string" } }
  }
}

user_get_usage

{
  "name": "user_get_usage",
  "inputSchema": {
    "type": "object",
    "properties": { "session_token": { "type": "string" } }
  }
}

user_get_saved_protocols

{
  "name": "user_get_saved_protocols",
  "inputSchema": {
    "type": "object",
    "properties": { "session_token": { "type": "string" } }
  }
}

admin_get_stats

{
  "name": "admin_get_stats",
  "inputSchema": {
    "type": "object",
    "properties": { "admin_session_token": { "type": "string" } }
  }
}

admin_list_users

{
  "name": "admin_list_users",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": { "type": "number", "default": 20 },
      "offset": { "type": "number", "default": 0 },
      "search": { "type": "string" },
      "admin_session_token": { "type": "string" }
    }
  }
}

admin_get_ai_costs

{
  "name": "admin_get_ai_costs",
  "inputSchema": {
    "type": "object",
    "properties": {
      "days": { "type": "number", "default": 30 },
      "admin_session_token": { "type": "string" }
    }
  }
}

身份验证

Hormonaly 使用两套独立的身份验证系统，请勿混用：

1. Helix Data API — Bearer Token

所有 /api/v1/* 端点都需要：Authorization: Bearer YOUR_API_KEY

API 密钥在存储前会经过 SHA-256 哈希处理。创建密钥时，明文密钥只会显示一次，请立即将其保存到密钥管理器中。如果密钥丢失，请撤销并轮换；无法恢复。REST /api/v1/* 端点要求在 Authorization: Bearer 标头中提供密钥；远程 MCP/SSE 服务要求在 x-api-key: hk_live_... 标头中提供密钥。

密钥管理：Partner Portal → API Keys (/partner/api)

2. Partner Portal — 会话身份验证

Partner Portal（/partner/*）使用基于会话的身份验证。使用电子邮件和密码在 /partner/login 登录。此会话不会授予数据 API 的访问权限。

密钥生命周期

1. 创建 — 完整密钥只会在模态框中显示一次，请立即复制。
2. 多个有效密钥 — 创建新密钥不会撤销现有密钥。
3. 撤销 — 即时生效。任何使用该密钥的请求都会立即返回 401。
4. 密钥丢失 — 撤销并创建新密钥。无法恢复明文。

速率限制与配额

方案	月度基础费用	包含 Token 数	速率限制	超额费率	硬性上限
API Starter	$499	5M tokens	60 req/min	$100 / 1M	10M tokens（之后返回 429）
API Advanced	$1,999	25M tokens	150 req/min	$80 / 1M	75M tokens（之后返回 429）
API Enterprise	$4,999	75M tokens	自定义	$25 / 1M	无（按超额用量计费）
旧版合作伙伴（计费前）	—	—	20 req/min	—	—

超限响应：HTTP 429，附带 Retry-After 标头。突发请求处理：采用滑动 60 秒窗口，不允许突发超额。

响应延迟

端点	P50 延迟
POST /api/v1/helix/query	3–12 秒
POST /api/v1/scribe/generate	15–45 秒
GET /api/v1/helix/protocols/:compound	< 200ms
run_clinical_workflow (MCP)	30–90 秒

usage 对象

每个 POST /api/v1/helix/query 响应都包含顶层 usage 对象，用于反映实时 Token 消耗：

{
  "usage": {
    "tokensUsedThisMonth": 1234567,
    "monthlyTokenBudget": 5000000,
    "percentUsed": 24.7,
    "hardCapTokens": 10000000,
    "hardCapExceeded": false,
    "quotaThresholdsCrossed": [80]
  }
}

错误与状态码

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request rate exceeded. Retry after 23s.",
    "request_id": "req_01HXYZ..."
  }
}

状态码	error.code	含义	建议的客户端行为
400	INVALID_REQUEST	JSON 格式错误或缺少必填字段	修正请求；不要原样重试
401	MISSING_AUTH	缺少 Authorization 标头	添加 Authorization: Bearer YOUR_API_KEY
401	INVALID_KEY	无法识别密钥或密钥已撤销	通过 Partner Portal 轮换密钥
403	TIER_REQUIRED	该端点要求 Advanced 或 Enterprise 方案	升级方案
404	NOT_FOUND	化合物、方案或作业 ID 不存在	验证标识符
422	VALIDATION_FAILED	语义验证失败	检查 error.message
429	RATE_LIMITED	超出每分钟请求速率限制	遵循 Retry-After 标头
429	BUDGET_EXCEEDED	超出调用前预算上限	等待预算窗口重置或联系计费支持
5xx	INTERNAL_ERROR	意外的服务器错误	使用指数退避重试（最多 3 次）
503	UPSTREAM_TIMEOUT	生物医学数据库或模型上游超时	5–10 秒后重试

订阅套餐

	API Starter	API Advanced	API Enterprise
月度基础费用	$499	$1,999	$4,999
每月包含的 Token 数	5,000,000	25,000,000	75,000,000
超额费率	$100 / 1M tokens	$80 / 1M tokens	$25 / 1M tokens
硬性上限	10M tokens — 随后返回 429	75M tokens — 随后返回 429	无（超额部分计费）
速率限制	60 req/min	150 req/min	自定义

功能	API Starter	API Advanced	API Enterprise
/api/v1/helix/query	是	是	是
/api/v1/scribe/generate	是	是	是
/api/v1/helix/dossier	否 — 403	是	是
/api/v1/helix/compare	否 — 403	是	是
白标门户	否	否	是
BAA（HIPAA）	否	否	是
专属支持	否	否	是

Scribe API

挂载于 /api/v1/scribe。所有套餐均可使用。

POST /scribe/generate

{
  "note_format": "soap",
  "patient_context": {
    "age": 45, "sex": "male",
    "diagnoses": ["hypogonadism"],
    "active_protocols": ["testosterone-cypionate"],
    "lab_values": { "total_testosterone": "250 ng/dL", "LH": "1.2 mIU/mL" }
  },
  "visit_notes": "Patient presents for quarterly follow-up."
}

支持的 note_format：soap | dap | narrative（默认值：soap）。响应包含 note、interaction_alerts、monitoring_plan、confidence_score、evidence_grade。延迟：15–45 秒。

GET /scribe/health

无需身份验证。

安全与合规

安全控制

控制项	实现方式
API 密钥存储	仅存储 SHA-256 哈希值 — 从不存储明文
速率限制	原子 SQL 计数器（滑动 60 秒窗口，可跨实例安全使用）
预算执行	调用前检查；消耗任何 LLM Token 前返回 429
会话固定攻击	每次登录时调用 regenerate()
IDOR 防护	所有档案和参与记录均经过所有权检查
批量赋值	无 — 所有输入均经过验证
搜索注入	所有 ILIKE/tsquery 均通过 Drizzle ORM 参数化
Webhook 安全	HMAC-SHA256 签名验证（Stripe + Resend）；所有事件均具备幂等性
路径遍历	所有文件服务端点均设有边界白名单
身份验证速率限制	所有身份验证端点均独立限流（由 PG 支持，可跨实例使用）
TLS	传输中使用 TLS 1.3；静态数据使用 AES-256 加密
WAF	Cloud Armor 已启用；扫描器流量已拦截
CSP / HSTS / CORS	所有标头均已配置；report-uri Sentry 遥测已启用
临床防护措施	NVIDIA NeMo · nvidia/llama-3.1-nemotron-nano-8b-v1（输入 PII 脱敏 + 离题过滤器）· nvidia/llama-3.3-nemotron-super-49b-v1（引用依据验证 + 剂量安全扫描）
供应链	package.json 中设为 private: true；依赖项审计无问题（2026 年 3 月）

合规状况

• 符合 HIPAA 的架构 — 默认不存储 PHI；除非明确启用 Clients 功能，否则患者数据仅限会话范围。
• 可提供 BAA — 企业客户可获得《业务伙伴协议》。
• 加密 — 传输中使用 TLS 1.3，静态数据使用 AES-256 加密，并提供地理冗余加密备份。
• 审计日志 — 所有身份验证事件、API 密钥使用情况、AI 调用和管理员操作均写入防篡改审计日志。
• 数据驻留 — 可按需提供 GCC 区域和欧盟数据驻留。
• 基础设施 — GCP（us-central1）、Cloud Run（自动扩缩容）、Cloud SQL PostgreSQL + pgvector。

GCP 继承以下认证：SOC 2 Type II、ISO 27001、HIPAA、PCI DSS，以及基础设施层的 150 多项合规认证。

AI 安全

• 每次查询均使用 NVIDIA NeMo 安全层：输入 PII 脱敏 + 离题/伤害导向框架过滤器（nvidia/llama-3.1-nemotron-nano-8b-v1，在 H100 上可自托管）；输出剂量安全扫描，并附带行内警告。
• 所有响应均启用 PEPTIDE_SAFETY_FOOTER 和 HELIX_REGULATORY_RULES。
• 不使用用户数据训练模型 — 查询数据不会用于训练或微调任何第三方模型。生产交互内容经过质量筛选后，仅用于 Hormonaly-1 Data Flywheel（参见 Hormonaly-1 LLM）。

内部基准测试（2026 年 5 月）：

维度	得分
引用依据验证通过率	100%
安全拦截率（针对已标记输入）	96%
RAG 检索通过率	99%
引用忠实度（经 PMID 验证）	97%

正常运行时间

• 目标 SLA — 所有生产 API 端点每月正常运行时间为 99.9%。
• P1 事件 — 15 分钟内确认，4 小时内解决。
• 状态 — status.hormonaly.ai
• 维护 — 至少提前 72 小时公告。

获取访问权限

1. 申请 Partner API 访问权限

联系 Hormonaly 团队，申请 Partner API 账户：

• 电子邮件： [email protected]
• 企业 / BD： hormonaly.ai/about
• 套餐： hormonaly.ai/pricing

您将通过电子邮件收到 API 密钥和 cURL 快速入门示例，此外还会收到单独的 Partner Portal 邀请，用于在 /partner/dashboard 设置您的仪表板。

2. 申请 Hormonaly-1 LLM 许可

面向有意为白标或嵌入式临床 AI 部署申请 Hormonaly-1 许可的企业集成商：

• LLM 许可： [email protected] — 主题：Hormonaly-1 Licensing Inquiry
• LLM 页面： hormonaly.ai/hormonaly-llm

有关模型的完整详情和许可层级，请参阅 Hormonaly-1 LLM 部分。

3. 首次 API 调用

curl -X POST https://hormonaly.ai/api/v1/helix/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the evidence for semaglutide in metabolic optimization?", "stream": false}'

4. OpenAPI 规范

curl https://hormonaly.ai/api/v1/helix/openapi.json

5. 完整文档

资源	URL
API 参考	hormonaly.ai/api-docs
技术手册	hormonaly.ai/manual
Partner Portal	hormonaly.ai/partner/login
集成指南	hormonaly.ai/integration-guide
平台	hormonaly.ai
关于 / 领导团队	hormonaly.ai/about
状态	status.hormonaly.ai

三维评分

Three-Lens 是 Hormonaly 专有的多领域证据评分框架。它通过三个临床视角独立评估一种复合物，提供各视角的疗效和安全性评分、证据等级（A–E）以及综合总体建议。

视角

视角	领域标签	重点	关键终点
longevity	长寿与抗衰老	减缓或逆转生物衰老，以延长健康寿命和寿命	表观遗传时钟减速、端粒动态、衰老细胞清除、NAD+ 水平、线粒体功能、自噬标志物
health_disease	健康与疾病预防	检测、预防或逆转慢性疾病	CVD 风险降低、HbA1c、炎症标志物（CRP、IL-6）、血压、血脂谱、胰岛素敏感性
performance	性能优化	提升认知、代谢和身体机能，使其超越基线水平	VO2max、握力、认知处理速度、睡眠质量、身体成分、HRV、运动后恢复

评分结构

每个视角都会返回一个 DomainScore 对象：

{
  "domain": "longevity",
  "domainLabel": "Longevity & Anti-Ageing",
  "efficacyScore": 7.4,
  "safetyScore": 8.1,
  "evidenceLevel": "C",
  "evidenceLevelLabel": "Low",
  "studyCount": 12,
  "bestStudyType": "Randomized Controlled Trial",
  "keyFindings": ["Demonstrated mTOR inhibition in human pilot (n=24)"],
  "limitations": ["Most trials are short-duration (<12 weeks)"],
  "relevantEndpoints": ["HbA1c", "fasting insulin", "body weight"]
}

证据等级（5 级）

等级	标签	描述
A	高	多项结果一致的 RCT 或荟萃分析
B	中	至少一项 RCT 或多项队列研究
C	低	病例系列、观察性研究
D	极低	专家意见 / 轶事证据
E	临床前	仅有动物或体外研究

总体建议

判定	含义
ADOPT	有力且一致的人体证据支持使用
CONSIDER	有合理证据——在知情同意并进行监测的情况下使用
WATCH_AND_WAIT	有积极信号，但证据不足以支持常规使用
AVOID	证据表明不宜使用，或存在不可接受的安全风险
INSUFFICIENT_DATA	数据太少，无法进行有意义的评分

请求 Three-Lens 评分

当 include_three_lens: true 时，helix_query 会返回 Three-Lens；helix_deep_analysis 和 run_clinical_workflow 则始终会返回：

curl -X POST https://hormonaly.ai/api/v1/helix/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the evidence for rapamycin in longevity?", "include_three_lens": true}'

Webhook 事件

Hormonaly 会将异步作业结果（档案、批量操作）发送到合作伙伴配置的 webhook URL。在 Partner Portal 的 Settings → Webhooks 下进行配置。

事件类型

事件	触发条件	负载字段
job.completed	异步作业成功完成	job_id, type, status: "completed", result, completed_at
job.failed	异步作业在所有重试后仍失败	job_id, type, status: "failed", error, completed_at

签名验证

每次交付都会使用 HMAC-SHA256 签名。签名位于 X-Hormonaly-Signature 标头中：

X-Hormonaly-Signature: sha256=<hex_digest>

const crypto = require('crypto');
function verifyWebhook(secret, rawBody, receivedSig) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(receivedSig));
}

交付策略：最多尝试 3 次，采用指数退避（1s → 8s → 64s），每次尝试超时为 10s，HTTP 2xx 表示交付成功。

API 版本控制与稳定性

当前版本：/api/v1/

层级	标识	承诺
稳定版	无标签	提前 ≥ 90 天公告重大变更；弃用后至少支持旧版本 6 个月
Beta 版	文档中标注 (beta)	接口可能变更；尽力保持稳定
已弃用	文档中标注 (deprecated)	计划移除；已记录迁移路径

更新日志

日期	变更
2026 年 6 月	Hormonaly-1 LLM 正式发布 — 专有临床大模型已在 NVIDIA H100 基础设施上投入使用；公开文档新增完整模型卡、许可路径和 API 集成说明
2026 年 6 月	修正超额用量费率：Starter 为 $100/1M，Advanced 为 $80/1M，Enterprise 为 $25/1M；设计合作伙伴更新为 21 家；新增 Hormonaly Library
2026 年 6 月	将状态表情符号替换为文本标签，使格式更简洁；新增 Anabol.ai 消费者危害减轻平台
2026 年 6 月	新增投资方和战略合作伙伴：KBW Ventures（被投公司）以及 NVIDIA Inception / Innovation Lab 拨款
2026 年 6 月	更新 NVIDIA 模型：NeMo 护栏升级为 nvidia/llama-3.1-nemotron-nano-8b-v1；记录 NIM 推理模型 nvidia/llama-3.3-nemotron-super-49b-v1
2026 年 6 月	修正 Query Pipeline 和 Model Routing 中的层级回退链：TIER_2 现显示 3 级链；TIER_3 现显示 4 级链
2026 年 5 月	后台 Agent 数量更新为 ×6；更新模型路由；记录分层令牌预算；发布完整的 24 个工具 MCP 架构；新增 Three-Lens Scoring、Webhook Events、API Versioning 章节

Hormonaly-1 LLM

已上线 · 2026 年 6 月 · NVIDIA Innovation Lab 拨款 · NIM Stack · H100 · Nemotron 49B · 阿拉伯语和英语

Hormonaly-1 是 Hormonaly 专有的临床大模型，专为肽类、激素和代谢医学设计。该模型已在 Hormonaly 自有的 NVIDIA H100 基础设施上通过 NVIDIA NIM 推理栈完成训练、合并和部署，推理时完全不依赖第三方 AI API。

概览

属性	值
模型名称	Hormonaly-1
基础模型	nvidia/llama-3.3-nemotron-super-49b-v1（Nemotron Super 49B）
训练方法	采用 LoRA 的监督微调（SFT）——经过质量筛选的临床平台交互数据
领域	肽类、激素和代谢医学
语言	阿拉伯语（عربي）+ 英语——原生双语
上下文窗口	131,072 个令牌
吞吐量	约 65 个令牌/秒
推理栈	NVIDIA NIM（可自托管）
硬件	8× NVIDIA H100 SXM GPU
状态	已上线 — 2026 年 6 月
支持	NVIDIA Inception 成员 + NVIDIA Innovation Lab 拨款获得者

能力

大规模临床推理 — 通过 LoRA 监督微调（SFT），直接基于真实临床平台交互数据训练。能够理解临床细微差别、禁忌症和剂量背景，涵盖 594+ 项方案和 10,000+ 篇已索引研究。

双语：阿拉伯语和英语 — 首个同时针对中东和北非（MENA）及英语医疗市场优化的临床大模型。在训练数据和推理中，两种语言都占据核心地位。

NVIDIA NIM 技术栈 — 基于 NVIDIA NIM 推理技术栈构建，Nemotron Super 49B 部署于 8×H100 SXM GPU 上。上下文窗口为 131k token，速度为 65 tok/s，可支持实时临床工作流。

基于证据等级的安全机制 — 每条响应都沿用 Helix 的证据分级流程：GRADE 风格评分（A–D）、经 PMID 验证的引文，以及 NeMo 安全护栏。Hormonaly-1 不会虚构引文——未经验证的 PMID 会在交付前被剔除。

推理时零第三方依赖 — 通过 Data Flywheel 流程持续记录并进行质量筛选真实平台交互，逐步减少对第三方大模型 API 的依赖。

Data Flywheel 与训练流程

Hormonaly-1 由 Data Flywheel 流程训练而成，这是一个在同一套 H100 基础设施上运行的持续改进循环：

1. 记录来自 Helix API 和 MCP 服务的生产环境交互，并进行质量筛选（引文忠实度、临床连贯性、安全标记审核）。
2. 在 H100 GPU 4–7 上运行 NeMo 监督微调（SFT）（LoRA，基座模型：nvidia/llama-3.3-nemotron-super-49b-v1）。
3. 合并后的模型检查点在部署到推理环境之前，会先通过内部临床基准测试验证。
4. NVIDIA NIM 在 GPU 0–3 上提供合并后模型的服务，用于生产环境推理。

该流程部分由 NVIDIA Innovation Lab 资助，并获得 NVIDIA Inception 会员计划支持。

API 集成

Hormonaly-1 通过相同的 Helix API 端点提供服务——集成方无需更改架构。Hormonaly-1 在路由链中启用时，响应元数据中会包含额外的 model 字段：

{
  "type": "metadata",
  "evidence_grade": "B",
  "confidence": 78,
  "verdict": "CONSIDER",
  "citations": 7,
  "model": "hormonaly-1",
  "inference_provider": "nvidia-nim-self-hosted"
}

inference_provider: "nvidia-nim-self-hosted" 字段用于区分 Hormonaly-1 响应与第三方模型响应。

许可

Hormonaly-1 提供企业许可，可用于白标或嵌入式临床 AI 部署。许可层级包括：

• API 访问 — 通过 Helix API 使用 Hormonaly-1，并享有完整的证据流程
• 嵌入式部署 — 在合作伙伴自己的 NVIDIA 基础设施中自托管 Hormonaly-1
• 白标 — 以您的临床产品品牌提供 Hormonaly-1

如需申请许可：

• 电子邮件： [email protected]（主题：Hormonaly-1 Licensing Inquiry）
• 网站： hormonaly.ai/hormonaly-llm
• 1 个工作日内回复。

模型卡摘要

维度	详情
预期用途	为持证医疗服务提供者提供临床决策支持、方案查询、证据综合和病历记录生成
非预期用途	消费者自我诊断、紧急医疗指导，或取代持证临床医生的判断
训练数据	经质量筛选的临床平台交互数据（Helix API、MCP），并辅以精选临床文献
安全措施	NVIDIA NeMo 安全护栏（PII 脱敏、剂量安全扫描）、PEPTIDE_SAFETY_FOOTER、HELIX_REGULATORY_RULES
输出免责声明	每条响应均包含医疗免责声明；输出仅作补充，不会取代持证临床医生的判断
数据隐私	不存储 PHI；数据仅限会话使用；训练数据经过去标识化和质量审核

关于 Hormonaly

Hormonaly 由 Fady Hannah-Shmouni, MD FRCPC 创立。他是一位通过专科认证的内分泌学家和遗传学家，曾接受 NIH 培训，现任 UBC 教授，发表过 100 多篇同行评审论文（h 指数为 27），并共同撰写了两项国际临床指南。

领导团队： Fady Hannah-Shmouni, MD FRCPC（CEO/CBO/创始人） · Omar Saleem, MD（AI Academy 负责人） · Matt D. Kramer（医疗技术策略师）

顾问委员会： Ali Mostashari, PhD（LifeNome） · Constantine Stratakis, MD（ASTREA） · Cory S. Goldberg, MD · John Kozman（Supernatural） · Dominik Thor, MSc（GCLS） · Labib Ghulmiyyah, MD · Zahraa Abdul Sater, MBBS

支持方： Hormonaly 是 KBW Ventures 的投资组合公司。KBW Ventures 是由 Prince Khaled bin Alwaleed bin Talal 创立的全球投资公司。Hormonaly 也是 NVIDIA Inception 成员，并获得 NVIDIA Innovation Lab 资助，可获得加速计算资源和工程支持，用于构建适用于肽类和激素医学的临床级、领域专用 AI 模型。生产环境中，一台可自托管的 8×H100 SXM 节点运行着三项 NVIDIA NIM 微服务：nvidia/llama-3.3-nemotron-super-49b-v1（用于引用依据和 Ask Hormonaly 副驾驶的 LLM 推理）、nvidia/llama-3.1-nemotron-nano-8b-v1（NeMo 安全护栏：PII 编辑 + 剂量安全）以及一项 Rerank NIM；此外，还运行着 Hormonaly-1 Data Flywheel pipeline，该流程使用 H100 GPU 4–7 上的 NeMo SFT 对 Hormonaly-1 进行微调（基础模型：nvidia/llama-3.3-nemotron-super-49b-v1；使用高质量生产交互数据进行 LoRA 微调），逐步降低对第三方 API 的依赖。

设计合作诊所与合作伙伴（21 家）： FORM Face + Body、REBORNE Longevity、Healthspan Digital、PearlMD、Toronto Functional Medicine Centre、A-Life、Astrea Health、Valeo Health、Celia Holdings、Celia Rx、Pillvery 等。

教育合作伙伴： DrVibe.ai（在 5 个国家培训了 1,000 多名临床医生） · GCLS.ai（Geneva College of Longevity Science）。

Hormonaly Library（hormonaly.com）： 基于循证依据的激素健康书籍和可下载 PDF 指南，由 Fady Hannah-Shmouni, MD FRCPC 撰写，包括 The Peptide Pocket Guide、Peptides Simplified、BPC-157: Evidence Simplified、Peptides, Hormones & Longevity，以及 Aesthetic & Regenerative Endocrinology（附阿拉伯语版本和免费样本）。

Anabol.ai（anabol.ai）： 由 Hormonaly 提供支持的免费面向消费者的平台，专注于危害降低与教育。提供关于类固醇、肽类、SARMs 和再生化合物的 AI 研究，并按证据等级分类。仅供教育参考，不构成医疗建议。

企业服务 — TelehealthOS 与 Canvas Medical： 面向企业护理团队，Hormonaly 提供 TelehealthOS——一套定制的 AI 原生基础设施，用于推出和扩展肽类、激素、护肤及长寿远程医疗业务。通过与 Canvas Medical 合作，企业客户可获得通过 HIPAA、SOC 2 和 HITRUST 认证的临床基础设施：支持 EPCS 的认证电子处方服务、集成式 EHR/EMR，以及通过 503A 和 503B FDA 注册的 cGMP 药房提供的配药服务。请联系 [email protected]，或访问 hormonaly.ai/telehealth-os。

---

Hormonaly 是一个教育与临床决策支持平台。所有 AI 输出旨在辅助而非取代持牌医疗专业人员的临床判断。每条回复均附有医疗免责声明。如需报告安全问题，请发送邮件至 [email protected]，或使用 GitHub 私密漏洞报告功能。

此代码库不包含任何专有源代码。© Hormonaly — 保留所有权利。