中医舌诊项目实战保姆级教程，3步搞定后端接口开发

面试被问原理答不上来，是不是经常遇到这种情况？很多后端开发在面试中医健康类项目时，一问到舌诊图像识别的底层逻辑，就卡壳了。别慌，今天这篇保姆级教程，带你从零搭建一个中医舌诊后端服务，代码直接跑通。

项目目标与需求拆解

我们要构建一个轻量级的中医舌诊API服务。核心功能包括：接收用户上传的舌苔照片，返回舌色、舌形、苔质等特征分析结果。

这里有个关键细节：中医舌诊讲究“望闻问切”，舌诊是“望”的核心。但在工程化落地时，我们不需要实现复杂的AI视觉模型，而是通过结构化数据接口来模拟诊断逻辑。这样既能满足业务需求，又能避免引入庞大的模型依赖，保持服务的轻量化。

技术栈选择：Python + FastAPI。为什么选这个组合？因为FastAPI自带类型检查和文档生成，对于医疗类这种对数据准确性要求高的场景，类型安全至关重要。

项目目标明确后，我们需要定义清楚输入输出格式。输入是Base64编码的舌苔图片，输出是JSON格式的诊断建议。这个设计参考了主流医疗API的设计规范，确保接口标准化。

目录结构规划

一个清晰的项目结构，能让代码维护事半功倍。我们采用分层架构，将业务逻辑、数据模型、工具函数分离。

tongue-diagnosis-api/
├── main.py              # FastAPI应用入口
├── config.py            # 配置管理
├── models/
│   ├── __init__.py
│   └── tongue.py        # 舌诊数据模型
├── services/
│   ├── __init__.py
│   └── diagnosis.py     # 诊断核心逻辑
├── utils/
│   ├── __init__.py
│   └── image_processor.py # 图像处理工具
└── requirements.txt     # 依赖清单

这种结构的优势在于：模型层只负责数据结构定义，服务层专注业务逻辑，工具层处理通用功能。当需要扩展新的舌诊特征时，只需在services层添加逻辑，不需要改动模型或入口文件。

requirements.txt中我们需要安装的核心依赖包括：fastapi、uvicorn、pydantic、Pillow。Pillow用于处理图片格式验证，pydantic负责数据校验，这两者是医疗类API的标配。

核心代码实现

先来看数据模型定义。在models/tongue.py中，我们用pydantic定义输入输出结构：

from pydantic import BaseModel, Field
from enum import Enumclass TongueColor(str, Enum):PINK = "pink"      # 淡红色，正常RED = "red"        # 红色，热证PALE = "pale"      # 淡白，寒证PURPLE = "purple"  # 紫暗，瘀血class TongueCoating(str, Enum):THIN = "thin"      # 薄苔THICK = "thick"    # 厚苔SLIPPERY = "slippery"  # 滑苔DRY = "dry"        # 燥苔class TongueDiagnosisInput(BaseModel):image_base64: str = Field(..., description="Base64编码的舌苔图片")patient_age: int = Field(..., ge=0, le=120, description="患者年龄")class TongueDiagnosisOutput(BaseModel):tongue_color: TongueColortongue_coating: TongueCoatingsuggestion: strconfidence: float

注意这里的Field参数，ge和le指定了年龄的有效范围。这种严格的数据校验，在医疗场景中是必须的。参考开发者文档中的最佳实践，所有输入参数都必须有明确的边界约束。

接下来是核心诊断逻辑。在services/diagnosis.py中，我们实现一个简单的规则引擎：

from models.tongue import TongueColor, TongueCoating, TongueDiagnosisOutput
from utils.image_processor import analyze_image_featuresdef perform_diagnosis(image_base64: str, age: int) -> TongueDiagnosisOutput:# 1. 分析图片特征features = analyze_image_features(image_base64)# 2. 根据舌色判断证型if features['color'] in ['red', 'dark_red']:tongue_color = TongueColor.REDelif features['color'] in ['pale', 'white']:tongue_color = TongueColor.PALEelif features['color'] in ['purple', 'dark_purple']:tongue_color = TongueColor.PURPLEelse:tongue_color = TongueColor.PINK# 3. 根据苔质判断if features['coating_thickness'] > 0.7:tongue_coating = TongueCoating.THICKelif features['moisture'] > 0.8:tongue_coating = TongueCoating.SLIPPERYelif features['moisture'] < 0.3:tongue_coating = TongueCoating.DRYelse:tongue_coating = TongueCoating.THIN# 4. 生成建议suggestion = generate_suggestion(tongue_color, tongue_coating, age)return TongueDiagnosisOutput(tongue_color=tongue_color,tongue_coating=tongue_coating,suggestion=suggestion,confidence=0.85)

这里的规则逻辑是简化的，实际项目中需要接入更复杂的中医知识图谱。但作为演示，这个结构足够清晰。每个判断分支都有明确的业务含义，代码可读性很高。

图像处理工具在utils/image_processor.py中：

import base64
from PIL import Image
import iodef analyze_image_features(image_base64: str) -> dict:"""分析舌苔图片特征注意：这里使用简单的颜色直方图模拟，实际应使用AI模型"""# 解码Base64image_data = base64.b64decode(image_base64)image = Image.open(io.BytesIO(image_data))# 转换为RGBimage = image.convert('RGB')# 简单特征提取：计算平均颜色width, height = image.sizepixels = list(image.getdata())avg_r = sum(p[0] for p in pixels) / len(pixels)avg_g = sum(p[1] for p in pixels) / len(pixels)avg_b = sum(p[2] for p in pixels) / len(pixels)# 简化判断：基于RGB值映射if avg_r > 150 and avg_g < 100 and avg_b < 100:color = 'red'elif avg_r < 120 and avg_g < 120 and avg_b < 120:color = 'pale'elif avg_r > 100 and avg_b > 100:color = 'purple'else:color = 'pink'# 模拟苔质判断coating_thickness = 0.5  # 实际需要分析纹理moisture = 0.6           # 实际需要分析光泽return {'color': color,'coating_thickness': coating_thickness,'moisture': moisture}

这个工具函数的关键点在于：它把复杂的图像分析抽象成简单的特征字典。当未来需要替换为真正的AI模型时，只需修改这个函数的内部实现，外部调用代码完全不用改动。这就是分层架构的威力。

运行与测试

主入口main.py配置FastAPI应用：

from fastapi import FastAPI, HTTPException
from models.tongue import TongueDiagnosisInput, TongueDiagnosisOutput
from services.diagnosis import perform_diagnosis
from utils.image_processor import analyze_image_featuresapp = FastAPI(title="中医舌诊API",version="1.0.0",description="基于图像分析的舌诊特征识别服务"
)@app.post("/api/tongue/diagnose", response_model=TongueDiagnosisOutput)
def diagnose_tongue(input_data: TongueDiagnosisInput):try:# 验证图片有效性if not input_data.image_base64:raise HTTPException(status_code=400, detail="图片数据为空")# 执行诊断result = perform_diagnosis(input_data.image_base64,input_data.patient_age)return resultexcept Exception as e:raise HTTPException(status_code=500, detail=f"诊断失败: {str(e)}")@app.get("/health")
def health_check():return {"status": "healthy"}

启动服务：