cogstacksystems/medcat-service

MedCAT Service 镜像文档

镜像概述和主要用途

本项目将https://github.com/CogStack/MedCAT/ NLP应用封装为REST API服务，通过Flask框架构建接口，支持接收文本输入并返回医学实体注释结果。核心功能是将MedCAT的NLP能力通过标准化API对外提供，便于集成到各类医学文本处理系统中。

核心功能和特性

API规范

API设计遵循https://github.com/CogStack/gate-nlp-service/标准，提供以下端点（均采用JSON格式交互）：

• GET /api/info：返回服务基本信息
• POST /api/process：处理单个文档并返回注释结果
• POST /api/process_bulk：批量处理多个文档并返回注释结果

完整API规范可参考https://github.com/CogStack/gate-nlp-service/tree/devel/api-specs。

使用场景和适用范围

适用于医学文本的NLP分析场景，如电子健康记录（EHR）实体提取、医学文献术语识别、临床笔记语义分析等。可作为后端服务集成到***信息系统、科研数据分析平台等应用中。

详细使用方法和配置说明

运行方式

支持两种运行方式：独立Python应用（需手动配置依赖）和Docker容器（推荐，环境隔离性好）。

作为Python应用运行

需先安装requirements.txt中的依赖包，提供两种启动脚本：

• start-service-dev.sh：开发模式，使用werkzeug服务器
• start-service-prod.sh：生产模式，使用gunicorn服务器

以Docker容器运行（推荐）

镜像获取

• 直接拉取：docker pull docker.xuanyuan.run/cogstacksystems/medcat-service:latest
• 手动构建：docker build -t medcat-service .（基于项目根目录的Dockerfile）

容器启动命令

bash
docker run -it -p 5000:5000 \
  --env-file=envs/env_app --env-file=envs/env_medcat \
  -v <本地模型目录>:/cat/models:ro \
  docker.xuanyuan.run/cogstacksystems/medcat-service:latest

• 端口映射：默认暴露5000端口，可通过-p参数调整
• 环境配置：通过--env-file加载env_app（服务配置）和env_medcat（MedCAT库配置）
• 模型挂载：本地模型目录需挂载到容器内/cat/models（只读权限，ro）

示例启动脚本：项目提供./docker/run_example_medmen.sh，可自动下载示例模型、配置环境并通过Docker Compose启动服务（需先执行./models/download_medmen.sh下载模型）。

使用示例

假设服务运行在localhost:5000，处理包含医学术语的文本：

请求命令

bash
curl -XPOST http://localhost:5000/api/process \
  -H 'Content-Type: application/json' \
  -d '{"content":{"text":"The patient was diagnosed with leukemia."}}'

返回结果

json
{
  "result": {
    "text": "The patient was diagnosed with leukemia.",
    "annotations": [
      {
        "pretty_name": "leukemia",
        "cui": "C0023418",
        "tui": "T191",
        "type": "Neoplastic Process",
        "source_value": "leukemia",
        "acc": "1",
        "start": 31,
        "end": 39,
        "info": {},
        "id": "0",
        "meta_anns": {}
      }
    ],
    "success": true,
    "timestamp": "2019-12-03T16:09:58.196+00:00"
  }
}

注：注释结果取决于所用模型。项目提供基于https://github.com/chanzuckerberg/MedMentions的基础模型用于评估；使用SNOMED CT或https://www.nlm.nih.gov/research/umls/index.html的模型需获取相应版权授权。

配置说明

服务配置通过环境变量实现，通常在envs目录下的文件中定义：

MedCAT Service应用配置（env_app）

服务器配置

• SERVER_HOST：服务绑定地址（默认：0.0.0.0）
• SERVER_PORT：服务端口（默认：5000）
• SERVER_WORKERS：并行工作进程数（默认：1，仅生产模式生效）
• SERVER_WORKER_TIMEOUT：进程超时时间（秒，默认：300，仅生产模式生效）

应用功能配置

• APP_MODEL_NAME：模型名称（可选，信息性描述）
• APP_MODEL_CDB_PATH：概念数据库路径（必填）
• APP_MODEL_VOCAB_PATH：词汇表路径（必填）
• APP_MODEL_META_PATH_LIST：元注释模型路径列表（可选，路径间用:分隔）
• APP_BULK_NPROC：批量处理线程数（默认：8）
• APP_TRAINING_MODE：训练模式开关（默认：False）

MedCAT库配置（env_medcat）

MedCAT核心参数定义在envs/env_medcat*文件中，详细参数说明参见https://github.com/CogStack/MedCAT/。