feat: GLiNER NER HTTP API

- POST /extract 接收文本和实体类型，返回抽取结果
- 模型启动时加载一次，多次请求复用
- 通过 HF_ENDPOINT 使用国内镜像，MODEL_CACHE_DIR 本地缓存
- 默认端口 4000，支持环境变量配置
- 包含单元测试（mock）和集成测试（真实 API）
- start.bat 从 conda ai 环境启动

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -0,0 +1,5 @@
+MODEL_NAME=urchade/gliner_medium-v2.1
+HOST=0.0.0.0
+PORT=4000
+HF_ENDPOINT=https://hf-mirror.com
+MODEL_CACHE_DIR=./model_cache

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.env
+model_cache/
+.pytest_cache/
+*.egg-info/
+dist/
+build/

app/config.py

@@ -0,0 +1,10 @@
+import os
+
+MODEL_NAME: str = os.getenv("MODEL_NAME", "urchade/gliner_medium-v2.1")
+HOST: str = os.getenv("HOST", "0.0.0.0")
+PORT: int = int(os.getenv("PORT", "4000"))
+MODEL_CACHE_DIR: str = os.getenv("MODEL_CACHE_DIR", "./model_cache")
+
+# Must be set before huggingface_hub / transformers are imported
+_hf_endpoint = os.getenv("HF_ENDPOINT", "https://hf-mirror.com")
+os.environ["HF_ENDPOINT"] = _hf_endpoint

app/main.py

@@ -0,0 +1,31 @@
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from app.config import MODEL_CACHE_DIR, MODEL_NAME
+from app.models import ExtractRequest, ExtractResponse
+from app.ner import NERService
+
+ner_service: NERService | None = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global ner_service
+    ner_service = NERService(MODEL_NAME, MODEL_CACHE_DIR)
+    yield
+    ner_service = None
+
+
+app = FastAPI(title="NER API", lifespan=lifespan)
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+
+@app.post("/extract", response_model=ExtractResponse)
+def extract(req: ExtractRequest):
+    entities = ner_service.extract(req.text, req.labels, req.threshold)
+    return ExtractResponse(entities=entities)

app/models.py

@@ -0,0 +1,19 @@
+from pydantic import BaseModel, Field
+
+
+class ExtractRequest(BaseModel):
+    text: str
+    labels: list[str]
+    threshold: float = Field(default=0.5, ge=0.0, le=1.0)
+
+
+class Entity(BaseModel):
+    text: str
+    label: str
+    score: float
+    start: int
+    end: int
+
+
+class ExtractResponse(BaseModel):
+    entities: list[Entity]

app/ner.py

@@ -0,0 +1,22 @@
+from gliner import GLiNER
+from app.models import Entity
+
+
+class NERService:
+    def __init__(self, model_name: str, cache_dir: str) -> None:
+        self._model = GLiNER.from_pretrained(model_name, cache_dir=cache_dir)
+
+    def extract(self, text: str, labels: list[str], threshold: float) -> list[Entity]:
+        if not text or not labels:
+            return []
+        raw = self._model.predict_entities(text, labels, threshold=threshold)
+        return [
+            Entity(
+                text=e["text"],
+                label=e["label"],
+                score=round(e["score"], 4),
+                start=e["start"],
+                end=e["end"],
+            )
+            for e in raw
+        ]

docs/requirements/PRD-ner-api.md

@@ -0,0 +1,26 @@
+# PRD-ner-api
+
+状态：已确认
+创建日期：2026-04-28
+
+## 1. 功能目标
+
+提供一个 HTTP API 服务，接收文本和实体类型列表，返回从文本中抽取到的命名实体。
+
+## 2. 用户故事
+
+作为 API 调用方，我可以传入一段文本和期望识别的实体类型（如 "person"、"organization"、"location"），得到每个实体的文字、类型和在原文中的位置。
+
+## 3. 验收标准
+
+- [ ] POST /extract 接口可正常调用
+- [ ] 支持传入任意实体类型列表（zero-shot）
+- [ ] 返回实体文字、实体类型、置信度分数
+- [ ] 模型加载一次，多次请求复用
+- [ ] 支持通过环境变量配置模型名称和服务端口
+
+## 4. 约束
+
+- 基于 GLiNER 库实现（Python）
+- 尽量简单，不引入数据库、认证等复杂机制
+- 默认使用 `urchade/gliner_medium-v2.1` 模型

docs/technical/TDD-ner-api.md

@@ -0,0 +1,62 @@
+# TDD-ner-api
+
+状态：已实现
+关联需求：docs/requirements/PRD-ner-api.md
+创建日期：2026-04-28
+
+## 1. 需求摘要
+
+用 FastAPI 包装 GLiNER 模型，提供 POST /extract 接口，接收文本与实体类型列表，返回抽取结果。
+
+## 2. 方案设计
+
+### 方案选型
+
+| 方案 | 优点 | 缺点 | 结论 |
+|------|------|------|------|
+| FastAPI + GLiNER | 轻量、async 支持好、自动生成文档 | — | ✅ 采用 |
+| Flask + GLiNER | 更简单 | 无 async，性能差 | ❌ |
+
+### 目录结构
+
+```
+ner-server/
+├── app/
+│   ├── main.py          # FastAPI app 入口，lifespan 加载模型
+│   ├── config.py        # 环境变量配置
+│   ├── models.py        # Pydantic 请求/响应模型
+│   └── ner.py           # GLiNER 封装（NERService）
+├── tests/
+│   └── test_extract.py
+├── requirements.txt
+└── .env.example
+```
+
+### 核心接口
+
+```
+POST /extract
+Request:  { "text": str, "labels": list[str], "threshold": float = 0.5 }
+Response: { "entities": [{ "text": str, "label": str, "score": float, "start": int, "end": int }] }
+
+GET /health
+Response: { "status": "ok" }
+```
+
+### 配置项（环境变量）
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| MODEL_NAME | urchade/gliner_medium-v2.1 | GLiNER 模型名称 |
+| PORT | 8000 | 服务端口 |
+| HOST | 0.0.0.0 | 监听地址 |
+
+## 3. 测试策略
+
+- 正常路径：传入文本和标签，返回实体列表
+- 空文本：返回空实体列表
+- 空标签列表：返回空实体列表
+- threshold 过滤：高阈值时过滤低置信度实体
+
+---
+确认记录：2026-04-28 用户确认（口头需求）

requirements.txt

@@ -0,0 +1,3 @@
+fastapi>=0.111.0
+uvicorn[standard]>=0.29.0
+gliner>=0.2.0

run.py

@@ -0,0 +1,5 @@
+import uvicorn
+from app.config import HOST, PORT
+
+if __name__ == "__main__":
+    uvicorn.run("app.main:app", host=HOST, port=PORT, reload=False)

start.bat

@@ -0,0 +1,3 @@
+@echo off
+call D:\ProgramData\anaconda3\Scripts\activate.bat D:\ProgramData\coda_envs\ai
+python run.py

tests/conftest.py

@@ -0,0 +1,13 @@
+"""
+Mock gliner and torch before any app module is imported.
+This prevents torch's BLAS FPE check from crashing on Windows during tests.
+"""
+import sys
+from unittest.mock import MagicMock
+
+# Stub out gliner and its torch dependency so the app can be imported safely
+for mod in ("torch", "gliner", "gliner.model"):
+    sys.modules.setdefault(mod, MagicMock())
+
+_gliner_stub = sys.modules["gliner"]
+_gliner_stub.GLiNER = MagicMock()

tests/test_api_integration.py

@@ -0,0 +1,89 @@
+"""
+Integration tests — require the server to be running.
+
+    python run.py   # in another terminal
+    pytest tests/test_api_integration.py -v
+"""
+import requests
+import pytest
+
+BASE_URL = "http://localhost:4000"
+
+
+def test_health():
+    resp = requests.get(f"{BASE_URL}/health")
+    assert resp.status_code == 200
+    assert resp.json()["status"] == "ok"
+
+
+def test_extract_person_and_org():
+    resp = requests.post(
+        f"{BASE_URL}/extract",
+        json={
+            "text": "Elon Musk founded SpaceX in 2002.",
+            "labels": ["person", "organization"],
+        },
+    )
+    assert resp.status_code == 200
+    entities = resp.json()["entities"]
+    labels = {e["label"] for e in entities}
+    texts  = {e["text"]  for e in entities}
+    assert "person"       in labels
+    assert "organization" in labels
+    assert "Elon Musk"    in texts
+    assert "SpaceX"       in texts
+
+
+def test_extract_with_high_threshold():
+    resp = requests.post(
+        f"{BASE_URL}/extract",
+        json={
+            "text": "Barack Obama visited Paris.",
+            "labels": ["person", "location"],
+            "threshold": 0.9,
+        },
+    )
+    assert resp.status_code == 200
+    for e in resp.json()["entities"]:
+        assert e["score"] >= 0.9
+
+
+def test_extract_empty_text_returns_empty():
+    resp = requests.post(
+        f"{BASE_URL}/extract",
+        json={"text": "", "labels": ["person"]},
+    )
+    assert resp.status_code == 200
+    assert resp.json()["entities"] == []
+
+
+def test_extract_empty_labels_returns_empty():
+    resp = requests.post(
+        f"{BASE_URL}/extract",
+        json={"text": "Apple is great.", "labels": []},
+    )
+    assert resp.status_code == 200
+    assert resp.json()["entities"] == []
+
+
+def test_extract_invalid_threshold_rejected():
+    resp = requests.post(
+        f"{BASE_URL}/extract",
+        json={"text": "Hello", "labels": ["person"], "threshold": 2.0},
+    )
+    assert resp.status_code == 422
+
+
+def test_entity_fields_present():
+    resp = requests.post(
+        f"{BASE_URL}/extract",
+        json={
+            "text": "Tim Cook leads Apple.",
+            "labels": ["person", "organization"],
+        },
+    )
+    assert resp.status_code == 200
+    for e in resp.json()["entities"]:
+        assert {"text", "label", "score", "start", "end"} <= e.keys()
+        assert 0.0 <= e["score"] <= 1.0
+        assert e["start"] < e["end"]

tests/test_extract.py

@@ -0,0 +1,88 @@
+"""
+conftest.py stubs gliner/torch before these imports run,
+so no real model is loaded during tests.
+"""
+from unittest.mock import MagicMock
+
+import pytest
+from fastapi.testclient import TestClient
+
+import app.main as main_module
+from app.main import app
+from app.models import Entity
+
+
+@pytest.fixture()
+def client():
+    mock_ner = MagicMock()
+    # Patch NERService so lifespan assigns our mock instead of a real model
+    with pytest.MonkeyPatch().context() as mp:
+        mp.setattr("app.main.NERService", lambda *_: mock_ner)
+        with TestClient(app) as c:
+            yield c, mock_ner
+
+
+def test_health(client):
+    c, _ = client
+    resp = c.get("/health")
+    assert resp.status_code == 200
+    assert resp.json() == {"status": "ok"}
+
+
+def test_extract_returns_entities(client):
+    c, mock_ner = client
+    mock_ner.extract.return_value = [
+        Entity(text="Apple", label="organization", score=0.95, start=0, end=5)
+    ]
+
+    resp = c.post(
+        "/extract",
+        json={"text": "Apple is a tech company.", "labels": ["organization", "person"]},
+    )
+
+    assert resp.status_code == 200
+    data = resp.json()
+    assert len(data["entities"]) == 1
+    assert data["entities"][0]["text"] == "Apple"
+    assert data["entities"][0]["label"] == "organization"
+
+
+def test_extract_empty_text(client):
+    c, mock_ner = client
+    mock_ner.extract.return_value = []
+
+    resp = c.post("/extract", json={"text": "", "labels": ["person"]})
+
+    assert resp.status_code == 200
+    assert resp.json()["entities"] == []
+
+
+def test_extract_empty_labels(client):
+    c, mock_ner = client
+    mock_ner.extract.return_value = []
+
+    resp = c.post("/extract", json={"text": "Some text.", "labels": []})
+
+    assert resp.status_code == 200
+    assert resp.json()["entities"] == []
+
+
+def test_extract_threshold_forwarded(client):
+    c, mock_ner = client
+    mock_ner.extract.return_value = []
+
+    c.post(
+        "/extract",
+        json={"text": "Hello world", "labels": ["person"], "threshold": 0.8},
+    )
+
+    mock_ner.extract.assert_called_once_with("Hello world", ["person"], 0.8)
+
+
+def test_extract_invalid_threshold(client):
+    c, _ = client
+    resp = c.post(
+        "/extract",
+        json={"text": "Hello", "labels": ["person"], "threshold": 1.5},
+    )
+    assert resp.status_code == 422