中医面舌辨证（tcm-face-tongue）#

何时使用#

• 用户上传 正脸照 → 走 face 模式（望面，输出体质 + 五脏分析 + 食谱）
• 用户上传 伸舌照 → 走 tongue 模式（望舌，输出舌象分类 + 体质 + 症状）
• 用户 同时 给出人脸 + 舌头两张图 → 走 combined 模式（面舌辨证，输出主/次体质与综合解读）

如不确定哪种模式，按以下优先级：

1. 如果手上同时有"face + tongue"两图 → combined（信息最完整）
2. 只有人脸 → face
3. 只有舌头 → tongue

接口元数据#

• 网关： https://gateway.ragehealth.cn/openapi-prod
• 请求方式： POST + multipart/form-data
• 认证头： AccessKey、 Signature（每次调用前重新生成）
• 三个接口：

模式path必填参数face``/face/tcm-analyse``imageUrl 或 imageFile``tongue``/face/tongue``imageUrl 或 imageFile``combined``/face/comprehensive-interpretation``faceImageUrl + tongueImageUrl（ 仅接受公网 URL）

关于 combined 的本地图片：官方接口只接 URL。当任一输入是本地文件时， call_tcm.py combined 会自动 客户端 fallback：分别调用 face + tongue 接口并把结果合并为 { faceTcm, tongueTcm, comprehensiveInterpretation: null, _clientFallback: true }。此时缺失服务端的 comprehensiveInterpretation.summary，需要由调用方根据 faceTcm + tongueTcm 自行综合解读。

公共可选参数（ face 与 combined）#

参数说明customerIp用户真实 IP（用于地域气候推断），优先级低于 province&city``province + city省 + 市， 必须成对传；不传则按 IP 自动推断fallbackProvince + fallbackCity兜底省市，前面所有定位手段都失败时使用age整数；不传则算法自动估计gender``0 =女 / 1 =男；不传则算法自动估计skinInfo肤质标签（ OSPW/油性/干性/中性/混性）；不传则算法自动检测faceIdDetect + userGroup是否开启人脸 ID 检测，开启时 userGroup 必填

tongue 模式 只接受 imageUrl / imageFile，不支持上述地理 / 人口学参数。

调用方式#

bash

# 望面（URL 或本地文件二选一）
python scripts/call_tcm.py face \
  --image-url https://example.com/face.jpg \
  [--province 广东省 --city 深圳市] [--age 30 --gender 0] [--skin-info 油性] \
  [--output face.json] [--full-stdout]

# 望舌
python scripts/call_tcm.py tongue \
  --image-file C:/path/to/tongue.jpg \
  [--output tongue.json]

# 面舌辨证：双 URL 走官方接口；任一为本地文件则自动 client-side fallback
python scripts/call_tcm.py combined \
  --face-image-url https://example.com/face.jpg \
  --tongue-image-url https://example.com/tongue.jpg \
  [--age 30 --gender 0] [--province 广东省 --city 深圳市] \
  [--output combined.json]

# 面舌辨证（fallback：本地图）
python scripts/call_tcm.py combined \
  --face-image-file C:/path/to/face.jpg \
  --tongue-image-file C:/path/to/tongue.jpg \
  --output combined.json

凭证由脚本自动从环境变量 TCM_AK / TCM_SK 读取， 不要 作为参数传入。首次使用前需前往 https://ragehealth.cn/client 注册申请 AK/SK，写入 scripts/.env（可与 skin-pro 共用同一对凭证）。脚本内部会生成 Signature 并以 multipart/form-data 提交。

执行步骤#

1. 判定模式：按上文"何时使用"的优先级选 face / tongue / combined。

2. 校验输入：图片 jpg/png；伸舌图需正面伸出、光线充足、无明显反光。

3. 调脚本：拿到 JSON； success=false 时提示用户重拍或检查图片质量。

4. 解读关键指标（按模式取）：

   • face（ data 直接挂）：

     • 基础： age / gender / display_img / face_color_region_show_url / occlusion.glasses
     • 大字段（默认会被脚本从 stdout 剥离，仅 --output 文件保留）： landmarks / raw_landmarks（478 个 [x,y] 关键点）
     • 五脏分析： report_items[]（每项 type ∈ {体质,心,肝,脾,肺,肾}），含 regions / syndromes / diseases / yin_score / yang_score / yin_yang_status / face_color / body_type / out_reason / emotion / analysis / suggests / disease_analysis / disease_suggests
     • 食谱： recipes[]（按 type 关联到对应 report_items），含 food_name / effect / ingredients / way / notice / food_image_url

   • tongue（ data 直接挂）：

     • 综合： score（0~100，越高越健康）、 overview
     • 体质： tiZhi.tizhiType + tiZhi.tiZhiReason
     • 症状： symptomArray[].{symptom, symptomReason}
     • 舌象分类： classify[].{className, classNameCn, category, score, resolution, deductionScore}，按 category 分组：舌形 / 舌神 / 舌色 / 苔色 / 苔质
     • 局部检测： detection.{boxes, polygon, scores, labels, classnames, classNamesCn, resolutions, deductionScores}（裂痕/齿痕/点刺；可能为空 dict 表示舌形正常）

   • combined（ data 直接挂）：

     • faceTcm / tongueTcm：分别是 face / tongue 接口的完整响应（结构同上）

     • comprehensiveInterpretation： 核心结论（client-side fallback 时为 null）

       • tizhi：综合体质（如 "湿热质"）
       • tizhi1 / prop1：主要体质 + 置信度
       • tizhi2 / prop2：次要体质 + 置信度
       • summary：综合解读
       • mainSymptom：主导体质的主要表现
       • auxiliarySymptom：兼夹体质 / 次要病理特征

     • _clientFallback：仅在 client-side fallback 时为 true，提示需要调用方自行综合 faceTcm + tongueTcm 给出解读

字段枚举字典（face / combined 的 report_items）#

部分字符串字段是固定枚举，直译可能让用户困惑，建议解读时映射成自然语言：

字段取值含义yin_yang_status``阴阳平和阴阳得分接近，状态最佳偏阴 / 偏阳轻度偏离阴虚 / 阳虚一方明显不足阴盛 / 阳盛一方明显亢盛face_color``发红多见热证、阳盛、心 / 肝火发青多见寒证、肝郁、瘀血发黄多见脾虚、湿证发白多见气虚、血虚、肺虚、寒证发黑多见肾虚、寒证、瘀血out_reason``风 / 寒 / 暑 / 湿 / 燥 / 火六淫外邪侵袭表现emotion``喜 / 怒 / 忧 / 思 / 悲 / 恐 / 惊七情对应的情志倾向（与五脏对应：心-喜、肝-怒、脾-思、肺-悲忧、肾-恐惊）body_type``平和质 / 气虚质 / 阳虚质 / 阴虚质 / 痰湿质 / 湿热质 / 血瘀质 / 气郁质 / 特禀质 / 气阴两虚中医九大体质（+气阴两虚）regions``阙中（眉间）/ 鼻柱 / 颜面（额）/ 左颊 / 右颊 / 下颌 等面诊分区，对应五脏定位

提示：当多个 report_items 的 yin_score / yang_score / body_type / out_reason / emotion 完全相同时，多半是接口用「整体体质」结论填充各脏腑默认值，单脏腑无需重复强调，可只在「综合体质」段引用一次。

1. 生成报告（建议骨架）：

   • 综合体质 + 置信度（combined 用 tizhi1/prop1 + tizhi2/prop2；单 face 用 report_items[type=体质]；单 tongue 用 tiZhi.tizhiType）
   • 五脏失衡 Top（face/combined 才有）：按 report_items 中阴阳得分偏离平衡显著的脏器
   • 舌象要点（tongue/combined 才有）：列出 classify 中 classNameCn != '正常' 的项 + 对应 resolution
   • 推荐食谱 / 调理建议：face 直接取 recipes；tongue 提取 symptomArray 配合体质给通用建议
   • 综合解读：combined 直接用 comprehensiveInterpretation.summary

安全 & 合规#

⚠️ 必须提醒：

• 中医辨证结果 仅供参考，不能替代执业中医师面诊
• 严重或持续症状应建议线下就诊
• 食谱仅为日常调理建议， 特殊体质 / 孕产妇 / 慢病患者 / 服药人群应遵医嘱
• 不在响应中泄露 AccessKey / SecretKey
• face_id / userGroup 涉及人脸特征数据， 仅在用户明确授权时启用 faceIdDetect，避免无差别记录

示例#

用户：帮我看下这两张照片（人脸 + 伸舌），分析下我现在的体质。

操作：

bash

python scripts/call_tcm.py combined \
  --face-image-url https://example.com/face.jpg \
  --tongue-image-url https://example.com/tongue.jpg \
  --province 广东省 --city 深圳市 \
  --output combined.json

回复（节选）：

• 综合体质： 湿热质（主，置信度 0.62）+ 气郁质（次，置信度 0.21）
• 主要表现：面色偏黄、舌红苔黄腻、口苦
• 五脏：肝阳偏盛，脾偏湿
• 调理：清热祛湿 + 疏肝解郁；推荐食谱：薏苡仁赤小豆汤
• 建议：清淡饮食、忌辛辣油腻、规律作息；持续不适请线下面诊