cookiecutter-spacy-fastapi API 完全参考：/entities 与 /entities_by_type 两个 NER 接口详解

cookiecutter-spacy-fastapi API 完全参考：/entities 与 /entities_by_type 两个 NER 接口详解

【免费下载链接】cookiecutter-spacy-fastapiCookiecutter API for creating Custom Skills for Azure Search using Python and Docker项目地址: https://gitcode.com/gh_mirrors/co/cookiecutter-spacy-fastapi

📌cookiecutter-spacy-fastapi是一个基于 Cookiecutter 的项目模板，帮你一键生成基于spaCy + FastAPI的命名实体识别（NER）API 服务，并支持 Docker 部署。它内置/entities与/entities_by_type两个 NER 接口，输出格式兼容 Azure Search 自定义认知技能（Cognitive Skill），是快速搭建命名实体抽取服务的实用脚手架。

上图：生成项目后访问/docs即可看到的 NER 接口在线文档与调试页面

一键生成你的 NER 服务：什么是 cookiecutter-spacy-fastapi

这个项目把三样东西打包成了一个模板：

它解决的核心痛点是：不用手写项目结构，直接得到带 Dockerfile、测试用例、示例请求、自动文档的完整服务。

快速上手步骤

1. 安装 Cookiecutter（需 1.4.0 或更高版本）：

pip install --user cookiecutter

2. 生成项目：

cookiecutter https://gitcode.com/gh_mirrors/co/cookiecutter-spacy-fastapi

生成后进入项目目录（路径名为{{cookiecutter.project_slug}}/），按模板提示填入 spaCy 默认模型名（如英文常用en_core_web_sm），即可运行。

两个接口共用的请求结构

理解请求体是调用两个接口的前提。请求由RecordsRequest模型定义（位于{{cookiecutter.project_slug}}/app/models.py），结构如下：

{ "values": [ { "recordId": "a1", "data": { "text": "Japan is a country. Washington is a state where most people speak English.", "language": "en" } } ] }

• values：文档列表，天然支持批量处理，一次请求可传多条文本；
• recordId：每条文档的唯一标识，响应中会原样带回，方便和原始数据对齐；
• data.text：待识别文本；
• data.language：语言代码，默认en。

这个values + recordId的设计正是 Azure Search 认知技能的标准入参约定，模板在{{cookiecutter.project_slug}}/app/data/example_request.json中内置了示例请求，/docs页面可直接填入试用。

/entities 接口详解：返回原始实体列表

POST /entities是最直接的 NER 接口：把一批文本送入 spaCy 模型，返回每条文档识别到的全部命名实体。

路由实现在{{cookiecutter.project_slug}}/app/api.py中，核心逻辑委托给{{cookiecutter.project_slug}}/app/spacy_extractor.py里的SpacyExtractor类，它通过nlp.pipe()批量处理文本，比逐条调用更快。

响应结构

{ "values": [ { "recordId": "a1", "data": { "entities": [ { "name": "Washington", "label": "GPE", "matches": [ {"start": 25, "end": 35, "text": "Washington"} ] } ] } } ] }

每个实体对象包含三个字段：

一个值得注意的细节：同一实体在文中出现多次时会被合并为一条记录，所有位置收进matches数组，而不是重复输出多条实体，响应更干净。

/entities_by_type 接口详解：按类型分组返回

POST /entities_by_type的请求体与/entities完全相同，区别在输出：它把每条文档的实体按标签分组，直接返回「类型 → 实体名列表」的结构：

{ "values": [ { "recordId": "a1", "data": { "organizations": ["Google", "Apple", "Amazon"], "products": ["Siri", "Alexa", "Echo and Dot"], "gpes": ["Japan", "Washington"] } } ] }

支持的 17 种实体类型

分组映射由ENT_PROP_MAP定义（位于{{cookiecutter.project_slug}}/app/models.py），覆盖 spaCy 默认模型的全部标签：

💡 这个接口可以直接作为Azure Search 自定义认知技能使用——响应中的字段名就是 Azure 侧可直接引用的属性名，无需二次转换。

两个接口怎么选？对比一览

经验法则：需要知道实体在原文哪个位置、或需要原始标签时，用/entities；只需要「这段文本里有哪些人、哪些公司」这种按类型归拢的结果时，用/entities_by_type。

本地运行与部署：从调试到 Docker

1. 进入生成的项目目录，创建虚拟环境并启动：

cd ./你的项目目录 bash ./create_virtualenv.sh uvicorn app.api:app --reload

2. 浏览器打开http://localhost:8000/docs即可看到上图所示的 NER 接口文档页；也可访问/redoc查看另一种文档样式。
3. 项目自带测试用例（{{cookiecutter.project_slug}}/app/tests/test_api.py），覆盖文档重定向和 NER 调用，可验证服务是否正常。
4. 部署时直接使用仓库内的{{cookiecutter.project_slug}}/Dockerfile：它基于 uvicorn-gunicorn-fastapi 基础镜像，自动执行spacy download拉取你在模板中指定的模型，容器监听 8080 端口，适合直接对接 Azure Search 或容器编排平台。

总结

cookiecutter-spacy-fastapi 用一条命令帮你搭好了一个生产可用的 NER 服务骨架：/entities给你带位置信息的原始实体，/entities_by_type给你按 17 种类型分组的整洁结果，两者入参相同、格式兼容 Azure Search 认知技能。对于想快速把 spaCy 实体识别能力暴露为 API 的团队，这套模板能省掉绝大部分脚手架工作，让你把精力留给模型选择和调优。

【免费下载链接】cookiecutter-spacy-fastapiCookiecutter API for creating Custom Skills for Azure Search using Python and Docker项目地址: https://gitcode.com/gh_mirrors/co/cookiecutter-spacy-fastapi