如何将 cookiecutter-spacy-fastapi 集成到 Azure Search：自定义认知技能实战教程

如何将 cookiecutter-spacy-fastapi 集成到 Azure Search：自定义认知技能实战教程

【免费下载链接】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 是一个开箱即用的 Python Cookiecutter 项目模板，只需一条命令，即可生成一个兼容Azure Search 自定义认知技能（Custom Cognitive Skill）的命名实体识别（NER）API 项目。它基于 spaCy + FastAPI + Docker 三大核心组件，帮你把文本智能分析能力快速接入 Azure Search 认知搜索，是新手构建企业级 NLP 技能服务的最短路径。

一、它是什么？为什么新手需要这个模板 🧩

先说清楚两个概念：

• Azure Search 认知技能（Cognitive Skill）：Azure Search 在索引文档时，可以调用各种 AI 能力（语言检测、实体识别、关键短语提取等），把分析结果写回索引，让搜索结果更"懂"你的数据。
• 自定义认知技能：如果你有一套自己的 AI 算法（比如一个 Python API），只要接口符合 Azure 规范，就能注册为"自定义认知技能"，融入 Azure Search 的技能流水线。

而cookiecutter-spacy-fastapi解决的就是：让你不用从零搭 API，直接生成一个符合自定义认知技能接口规范的 NER 服务。

核心组件	作用
spaCy	工业级自然语言处理库，负责加载模型并批量抽取实体
FastAPI	高性能 Python Web 框架，自动生成 OpenAPI 文档
Docker	一键打包部署，镜像内自动下载 spaCy 模型

二、一条命令生成你的 NER 项目 ⚡

1. 安装 Cookiecutter

pip install --user cookiecutter

2. 获取模板仓库

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

3. 运行生成器

cookiecutter ./cookiecutter-spacy-fastapi

生成器会依据cookiecutter.json中的变量定义，交互式地向你询问 4 个问题：

变量	说明
project_name	项目名，默认为 "spaCy FastAPI Azure Cognitive Skill"
project_slug	由项目名自动生成的目录名（下划线格式）
short_description	项目简介，自动生成
spacy_model	关键选项：选择 spaCy 官方预训练模型，如en_core_web_sm

回答完毕，一个完整的可运行项目就落在你的磁盘上了 🎉

三、生成的项目结构一览 📁

{{project_slug}}/ ├── app/ │ ├── api.py # FastAPI 路由：/entities 与 /entities_by_type │ ├── models.py # 请求/响应模型 + 实体类型映射表 │ ├── spacy_extractor.py # SpacyExtractor 批量实体抽取封装 │ ├── data/example_request.json # 示例请求报文 │ └── tests/test_api.py # 接口自动化测试 ├── main.py # 本地启动入口（uvicorn，0.0.0.0:8080） ├── Dockerfile # 容器镜像构建脚本 ├── requirements.txt # 依赖清单 └── README.md # 运行与部署说明

几个关键文件值得花 30 秒了解：

• app/api.py：应用启动时一次性加载 spaCy 模型（spacy.load），并注册两个 POST 路由，这是整个技能的门面。
• app/spacy_extractor.py：SpacyExtractor类使用nlp.pipe()对文档批量做实体抽取，比逐条处理高效得多，还负责把实体按名称归并、记录起止位置。
• app/models.py：定义了RecordsRequest/RecordsResponse等 Pydantic 模型——这正是 Azure Search 自定义认知技能的标准请求/响应格式；其中的ENT_PROP_MAP把 spaCy 的 18 种实体标签（PERSON、ORG、LOC、DATE、MONEY……）映射为技能接口友好的属性名（people、organizations、locations、dates、money……）。

四、本地运行：3 步调试你的 NER API 🐍

进入生成的项目目录，按顺序执行：

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

然后打开浏览器访问http://localhost:8000/docs，即可看到 FastAPI 自动生成的 OpenAPI 交互文档界面，直接在线调试接口：

上图：/entities接口的在线调试页面。把示例报文填入 Request body，点击 Execute 即可看到 spaCy 抽取出的命名实体。

项目还内置了app/data/example_request.json示例请求，测试时可一键填入；另有tests/test_api.py供你回归验证接口行为。

五、两个接口，一个"灵魂"：/entities_by_type 🎯

生成的 API 暴露了两个端点，理解它们的分工是接入 Azure Search 的关键：

1️⃣POST /entities—— 通用实体列表

输入一批带recordId和text的记录，返回每条记录抽取到的全部实体（名称、标签、文本位置）。适合本地开发调试或自有业务系统直接调用。

2️⃣POST /entities_by_type—— 技能接口（灵魂所在）✨

返回结果按实体类型分组，例如一段文本会被整理为：

{ "values": [ { "recordId": "a1", "data": { "organizations": ["Microsoft"], "products": ["Echo", "Dot"], "people": ["Siri", "Alexa"] } } ] }

这个结构完全对齐 Azure Search自定义认知技能接口规范，因此可以原样部署后注册进 Azure Search 的 Skillset 中。

接入流程可以概括为：

你的文档 → Azure Search 索引器 → 调用你部署的 /entities_by_type 端点 → spaCy 批量抽取实体 → 实体写回索引字段 → 用户可按人名/机构/地点/日期精准检索

简言之：部署 → 在 Azure 门户的索引器 Skillset 中登记你的 API 地址 → 索引时自动跑 NER，三步完成集成。

六、用 Docker 一键部署上线 🐳

生成的Dockerfile已做好全部准备：

• 基于tiangolo/uvicorn-gunicorn-fastapi生产级基础镜像
• 构建时自动执行spacy download {你选的模型}，把 NLP 模型打进镜像
• 服务监听 8080 端口，默认 2 个 Web 并发

构建并运行：

docker build -t my-ner-skill . docker run -p 8080:8080 my-ner-skill

镜像推到容器注册表后，即可部署到 Azure Kubernetes Service（AKS）等托管环境。项目的README.md中也提供了配合 Azure Pipelines 搭建 CI/CD 的指引，方便持续交付。

七、新手常见问题 FAQ 💬

Q1：spacy_model 可以随便填吗？不行。cookiecutter.json中明确要求它必须是 spaCy 官方预训练模型（如en_core_web_sm、en_core_web_md等）。小模型sm起步足够，追求精度再升md/lg。

Q2：模型加载会不会拖慢每次请求？不会。app/api.py在应用启动时只执行一次spacy.load，请求阶段用nlp.pipe()批量推理，性能友好。

Q3：我不打算用 Azure Search，这个 API 还有用吗？当然有。它就是一个标准 FastAPI 服务，/entities接口可直接服务于任何需要实体抽取的业务场景，Azure Search 集成属于"锦上添花"。

Q4：接口测试怎么跑？项目内置tests/test_api.py，启动服务后执行测试即可验证两个端点的行为是否符合预期。

八、小结 🏁

步骤	耗时	说明
生成项目	~1 分钟	一条 cookiecutter 命令
本地调试	~5 分钟	uvicorn 启动 + OpenAPI UI 在线测试
容器化部署	~10 分钟	Docker 构建 + 推送注册表
接入 Azure Search	视环境	在 Skillset 中登记 API 端点

cookiecutter-spacy-fastapi 把"spaCy 模型 + FastAPI 服务 + Docker 部署 + Azure Search 技能规范"这四件事打包成了一条命令。对新手而言，它是理解自定义认知技能接口规范的最佳范本；对团队而言，它是把自研 NLP 能力接入 Azure Search 认知搜索的快速通道。现在，去生成你的第一个命名实体识别技能吧 🚀

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