Skip to content

gitstq/MedTextCN

BranchesTags

Repository files navigation

MedTextCN Logo

MedTextCN

中文医疗文本智能分析工具包

Python License Version PRs Welcome

面向中文医疗场景的 NLP 工具包 — 实体识别、隐私脱敏、病历结构化，一行代码即可调用

语言版本

简体中文 | English | 繁體中文

项目介绍

MedTextCN 是一款专为中文医疗文本场景设计的自然语言处理工具包。在医疗信息化和智慧医疗快速发展的背景下，非结构化的中文病历文本蕴含着丰富的临床信息，但同时也面临着隐私保护和数据利用的双重挑战。

MedTextCN 旨在解决以下核心问题：

  • 医疗实体识别：从非结构化病历文本中精准提取疾病、症状、药物、检查、解剖部位、治疗方式等医学实体，为下游临床决策支持、医学知识图谱构建提供基础能力。
  • 患者隐私保护：自动检测病历中的个人身份信息（PII），支持多种脱敏策略，帮助医疗机构在数据共享和科研利用中满足《个人信息保护法》（PIPL）等法规的合规要求。
  • 病历文本结构化：将自由文本形式的病历自动解析为标准化的 SOAP 格式（Subjective、Objective、Assessment、Plan），提升病历数据的可用性和互操作性。

无论是医疗 AI 研发团队、医院信息化部门，还是医疗数据科学从业者，MedTextCN 都能为您提供开箱即用的中文医疗文本处理能力。

核心特性

🏥 中文医疗 NER 引擎

内置 831+ 医学实体知识库，覆盖 6 大类别：疾病（158）、症状（116）、药物（175）、检查（135）、解剖部位（163）、治疗方式（84）。基于规则与词典混合匹配策略，无需 GPU 即可实现高效的实体识别。

🔒 中文 PII 检测与脱敏

支持 8 种 PII 类型检测：身份证号、手机号码、患者姓名、医保卡号、电子邮箱、家庭地址、出生日期、就诊日期。提供 4 种脱敏模式：遮罩（mask）、替换（replace）、哈希（hash）、移除（remove），符合《个人信息保护法》（PIPL）合规要求。

📋 病历文本结构化

智能解析 9 种病历段落类型：主诉、现病史、既往史、个人史、家族史、体格检查、辅助检查、诊断、治疗方案。自动输出标准 SOAP 格式结构化结果，便于电子病历系统集成。

✂️ 医学增强分词器

基于 jieba 分词引擎进行医学领域增强，内置医学专业词库和实体优先匹配策略，有效解决医学长词、专业术语的分词难题。

⚡ 批量处理引擎

内置并发处理框架，支持大批量病历文本的并行处理，提供进度回调机制，可轻松集成到数据处理流水线中。

🌐 FastAPI REST 服务

开箱即用的 REST API 服务，提供 7 个 API 端点，覆盖综合分析、实体提取、PII 检测、文本脱敏、文本结构化、健康检查和 API 文档等完整功能。

💻 CLI 命令行工具

提供 analyze、serve、demo、version 四个命令，支持从终端直接进行文本分析、启动 API 服务、运行演示和查看版本信息。

🐳 Docker 容器化部署

提供完整的 Dockerfile，支持一键构建和部署，简化在服务器和云环境中的部署流程。

快速开始

环境要求

  • Python >= 3.9
  • pip（Python 包管理器）

安装

pip install medtextcn

一行代码上手

from medtextcn import analyze_text

# 一行代码完成综合分析（NER + PII检测 + 结构化）
result = analyze_text("患者张三，男，65岁，因糖尿病入院")

print(result)

输出示例：

{
  "entities": [
    {"text": "糖尿病", "type": "disease", "start": 12, "end": 15}
  ],
  "pii": [
    {"text": "张三", "type": "name", "start": 2, "end": 4}
  ],
  "structured": {
    "subjective": "患者张三，男，65岁，因糖尿病入院"
  }
}

详细使用指南

1. 医疗实体识别（NER）

从医疗文本中提取疾病、症状、药物、检查、解剖部位和治疗方式等实体。

from medtextcn import extract_entities

entities = extract_entities("高血压合并冠心病，需做心电图检查")

for entity in entities:
    print(f"实体: {entity['text']}, 类型: {entity['type']}, 位置: {entity['start']}-{entity['end']}")

输出：

实体: 高血压, 类型: disease, 位置: 0-3
实体: 冠心病, 类型: disease, 位置: 4-7
实体: 心电图, 类型: examination, 位置: 10-13

支持的实体类型：

类型 标签 内置数量 示例
疾病 disease 158 糖尿病、高血压、冠心病
症状 symptom 116 头痛、发热、咳嗽
药物 drug 175 阿莫西林、二甲双胍
检查 examination 135 血常规、心电图、CT
解剖部位 anatomy 163 心脏、肝脏、左肺
治疗方式 treatment 84 手术、输液、透析

2. PII 检测与脱敏

PII 检测

from medtextcn import detect_pii

pii_results = detect_pii("患者李四，身份证号110101199003076039，手机号13800138000")

for item in pii_results:
    print(f"类型: {item['type']}, 内容: {item['text']}")

输出：

类型: name, 内容: 李四
类型: id_card, 内容: 110101199003076039
类型: phone, 内容: 13800138000

文本脱敏

from medtextcn import deidentify_text

# 遮罩模式（默认）
safe = deidentify_text("患者王五，手机号15098765432", mode="mask")
print(safe)
# 输出: 患者王*，手机号150****5432

# 替换模式
safe = deidentify_text("患者王五，手机号15098765432", mode="replace")
print(safe)
# 输出: 患者[患者姓名]，手机号[手机号码]

# 哈希模式
safe = deidentify_text("患者王五，手机号15098765432", mode="hash")
print(safe)
# 输出: 患者a3f2e1...，手机号7b8c9d...

# 移除模式
safe = deidentify_text("患者王五，手机号15098765432", mode="remove")
print(safe)
# 输出: 患者，手机号

支持的 PII 类型：

类型 标签 说明
患者姓名 name 中文姓名识别
身份证号 id_card 18位身份证号码
手机号码 phone 11位手机号码
医保卡号 medical_card 医保卡编号
电子邮箱 email 邮箱地址
家庭地址 address 中文地址信息
出生日期 birth_date 出生日期
就诊日期 visit_date 就诊/入院日期

3. 病历文本结构化

将自由文本病历解析为标准 SOAP 格式。

from medtextcn import structure_text

text = """主诉：反复咳嗽3天。
现病史：3天前受凉后出现咳嗽，伴白色稀痰，无发热。
既往史：高血压病史5年，口服降压药控制。
体格检查：体温36.5℃，双肺呼吸音粗。
诊断：急性支气管炎。
治疗方案：抗感染治疗，对症处理。"""

structured = structure_text(text)
print(structured)

输出：

{
  "subjective": {
    "chief_complaint": "反复咳嗽3天。",
    "present_illness": "3天前受凉后出现咳嗽，伴白色稀痰，无发热。",
    "past_history": "高血压病史5年，口服降压药控制。"
  },
  "objective": {
    "physical_exam": "体温36.5℃，双肺呼吸音粗。"
  },
  "assessment": {
    "diagnosis": "急性支气管炎。"
  },
  "plan": {
    "treatment_plan": "抗感染治疗，对症处理。"
  }
}

4. 医学增强分词

from medtextcn import tokenize

tokens = tokenize("患者因急性心肌梗死入院，需行冠脉造影检查")
print(tokens)
# 输出: ['患者', '因', '急性心肌梗死', '入院', '，', '需', '行', '冠脉造影', '检查']

5. 批量处理

from medtextcn import batch_analyze

texts = [
    "患者张三，男，65岁，因糖尿病入院",
    "患者李四，女，45岁，高血压合并冠心病",
    "患者王五，男，72岁，慢性阻塞性肺疾病急性加重",
]

results = batch_analyze(texts, max_workers=4, progress_callback=lambda i, n: print(f"进度: {i}/{n}"))

6. FastAPI REST 服务

启动服务

medtextcn serve --host 0.0.0.0 --port 8080

API 端点

方法 路径 说明
POST /api/v1/analyze 综合文本分析
POST /api/v1/entities 实体提取
POST /api/v1/pii/detect PII 检测
POST /api/v1/pii/deidentify 文本脱敏
POST /api/v1/structure 文本结构化
GET /api/v1/health 健康检查
GET /docs API 文档（Swagger UI）

请求示例

# 综合分析
curl -X POST http://localhost:8080/api/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "患者张三，男，65岁，因糖尿病入院"}'

# 实体提取
curl -X POST http://localhost:8080/api/v1/entities \
  -H "Content-Type: application/json" \
  -d '{"text": "高血压合并冠心病，需做心电图检查"}'

# PII 检测
curl -X POST http://localhost:8080/api/v1/pii/detect \
  -H "Content-Type: application/json" \
  -d '{"text": "患者李四，身份证号110101199003076039"}'

# 文本脱敏
curl -X POST http://localhost:8080/api/v1/pii/deidentify \
  -H "Content-Type: application/json" \
  -d '{"text": "患者王五，手机号15098765432", "mode": "mask"}'

7. CLI 命令行工具

# 文本分析
medtextcn analyze "患者张三，男，65岁，因糖尿病入院"

# 启动 API 服务
medtextcn serve --host 0.0.0.0 --port 8080

# 运行演示
medtextcn demo

# 查看版本
medtextcn version

8. Docker 部署

# 构建镜像
docker build -t medtextcn .

# 运行容器
docker run -p 8080:8080 medtextcn

# 后台运行
docker run -d --name medtextcn-server -p 8080:8080 medtextcn

技术架构

MedTextCN 采用分层模块化架构设计，各模块职责清晰、松耦合，便于独立使用和扩展。

┌─────────────────────────────────────────────────────────┐
│                    接入层 (Access Layer)                  │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ CLI 命令 │  │ FastAPI REST │  │  Python SDK (API) │  │
│  └────┬─────┘  └──────┬───────┘  └─────────┬─────────┘  │
├───────┴───────────────┴───────────────────┴─────────────┤
│                   服务层 (Service Layer)                   │
│  ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
│  │ 综合分析器 │ │ 批量引擎 │ │ 脱敏引擎 │ │ 结构化引擎│  │
│  └─────┬──────┘ └────┬─────┘ └────┬─────┘ └─────┬─────┘  │
├────────┴──────────────┴───────────┴─────────────┴───────┤
│                   核心层 (Core Layer)                      │
│  ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
│  │ NER 引擎  │ │ PII 检测 │ │ 分词引擎 │ │ 段落解析器│  │
│  └─────┬──────┘ └────┬─────┘ └────┬─────┘ └─────┬─────┘  │
├────────┴──────────────┴───────────┴─────────────┴───────┤
│                   数据层 (Data Layer)                       │
│  ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
│  │ 医学实体库 │ │ PII 规则 │ │ 医学词库 │ │ 段落模板库│  │
│  │  (831+)   │ │  (8类)   │ │ (jieba+) │ │  (9类)    │  │
│  └────────────┘ └──────────┘ └──────────┘ └───────────┘  │
└─────────────────────────────────────────────────────────┘

模块说明：

模块 职责 关键技术
NER 引擎 医学实体识别 词典匹配 + 规则引擎
PII 检测 个人信息检测 正则表达式 + 上下文分析
分词引擎 医学文本分词 jieba + 医学词库增强
段落解析器 病历段落分类 模式匹配 + 关键词提取
脱敏引擎 文本脱敏处理 多策略脱敏管线
结构化引擎 SOAP 格式输出 段落分类 + 字段映射
批量引擎 并发批处理 ThreadPoolExecutor
REST 服务 HTTP API FastAPI + Pydantic

项目结构

medtextcn/
├── docs/
│   ├── logo.jpg                  # 项目 Logo
│   ├── README.en.md              # 英文版 README
│   └── README.zh-TW.md           # 繁体中文版 README
├── medtextcn/
│   ├── __init__.py               # 包入口，导出公共 API
│   ├── cli.py                    # CLI 命令行工具
│   ├── api/
│   │   ├── __init__.py
│   │   ├── app.py                # FastAPI 应用
│   │   ├── routes.py             # API 路由定义
│   │   └── schemas.py            # Pydantic 数据模型
│   ├── core/
│   │   ├── __init__.py
│   │   ├── ner.py                # NER 实体识别引擎
│   │   ├── pii.py                # PII 检测引擎
│   │   ├── tokenizer.py          # 医学增强分词器
│   │   └── parser.py             # 病历段落解析器
│   ├── services/
│   │   ├── __init__.py
│   │   ├── analyzer.py           # 综合分析服务
│   │   ├── deidentifier.py       # 脱敏服务
│   │   ├── structurer.py         # 结构化服务
│   │   └── batch.py              # 批量处理引擎
│   └── data/
│       ├── entities/             # 医学实体词典
│       │   ├── diseases.json     # 疾病实体 (158)
│       │   ├── symptoms.json     # 症状实体 (116)
│       │   ├── drugs.json        # 药物实体 (175)
│       │   ├── examinations.json  # 检查实体 (135)
│       │   ├── anatomy.json      # 解剖部位 (163)
│       │   └── treatments.json   # 治疗方式 (84)
│       ├── pii_patterns.json     # PII 检测规则
│       ├── section_patterns.json # 段落分类规则
│       └── medical_words.txt    # 医学分词词库
├── tests/
│   ├── test_ner.py               # NER 引擎测试
│   ├── test_pii.py               # PII 检测测试
│   ├── test_deidentify.py        # 脱敏功能测试
│   ├── test_structure.py         # 结构化测试
│   ├── test_tokenizer.py         # 分词器测试
│   └── test_api.py               # API 接口测试
├── Dockerfile                     # Docker 构建文件
├── setup.py                      # 包安装配置
├── pyproject.toml                # 项目元数据
├── README.md                     # 项目说明（本文件）
├── CONTRIBUTING.md               # 贡献指南
├── LICENSE                       # MIT 开源协议
└── .github/
    └── workflows/
        └── ci.yml                # CI/CD 配置

开发指南

环境搭建

# 克隆仓库
git clone https://github.com/gitstq/MedTextCN.git
cd MedTextCN

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# 安装开发依赖
pip install -e ".[dev]"

# 安装项目
pip install -e .

运行测试

# 运行全部测试
pytest tests/ -v

# 运行特定模块测试
pytest tests/test_ner.py -v
pytest tests/test_pii.py -v

# 查看测试覆盖率
pytest tests/ --cov=medtextcn --cov-report=html

代码规范

# 代码格式化
black medtextcn/ tests/

# 代码检查
flake8 medtextcn/ tests/

# 导入排序
isort medtextcn/ tests/

路线图

v1.1 — 增强与优化（计划中）

  • 扩展医学实体库至 2000+ 实体
  • 新增手术记录、护理记录等段落类型解析
  • 支持自定义实体词典加载
  • 性能优化：大文本处理速度提升 50%

v1.2 — 模型集成（规划中）

  • 集成预训练中文医疗语言模型（如 cBLUE、CMeKG）
  • 提供 BERT/BiLSTM-CRF 模型推理接口
  • 支持模型微调与自定义训练流水线
  • 实体识别 F1 值提升至 90%+

v2.0 — 平台化（远期规划）

  • 医学知识图谱构建工具
  • 多模态支持（影像报告、检验报告）
  • 临床决策支持（CDS）基础接口
  • 分布式部署与高可用架构
  • Web 可视化管理界面

贡献指南

我们欢迎并感谢任何形式的贡献！无论是提交 Bug 报告、改进文档，还是提交代码 Pull Request。

请阅读 贡献指南 了解详细的贡献流程和规范。

快速贡献流程：

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add some amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 创建 Pull Request

开源协议

本项目基于 MIT License 开源。

MIT License

Copyright (c) 2024 gitstq (琦琦)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

致谢

MedTextCN 的开发得益于以下优秀开源项目和技术社区的支持：

  • jieba — 结巴中文分词，MedTextCN 医学分词器的底层引擎
  • FastAPI — 高性能 Python Web 框架，为 REST API 提供基础支撑
  • Pydantic — 数据验证与序列化，确保 API 数据一致性
  • cBLUE — 中文医学语言理解基准，为模型评估提供参考
  • CMeKG — 中文医学知识图谱，实体库构建的重要参考
  • PyPI — Python 包索引，MedTextCN 的分发平台

感谢所有为中文医疗 NLP 领域做出贡献的研究者和开发者。

MedTextCN — 让中文医疗文本分析更简单

Made with ❤️ by gitstq (琦琦)

About

中文医疗文本智能分析工具包 - Chinese Medical Text Intelligence Toolkit | NER实体识别 | PII隐私脱敏 | 病历结构化 | PIPL合规

github.com/gitstq/MedTextCN

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

MedTextCN v1.0.0 - Initial Release Latest
Jun 11, 2026

Packages

 
 
 

Contributors

Languages