Pattern-based detection covers structured values: email addresses, card numbers, SSNs. Names are not structured, so detecting them needs a model. PhEye is the service that hosts those models, and a lens is the model it loads.
Running PhEye
The lens is baked into the image tag, so choosing a model means choosing a tag:
docker run -p 5000:5000 philterd/ph-eye:1.3.0-pii_en_small
The first start downloads the model, so give it a moment. GET /health returns 200 once
it is ready.
Calling it directly
curl -X POST http://localhost:5000/find \
-H "Content-Type: application/json" \
-d '{"text":"Please forward the invoice to Toni Levine and copy Maria Gonzalez."}'
[
{ "label": "name", "text": "Toni Levine", "score": 0.9966, "start": 30, "end": 41 },
{ "label": "name", "text": "Maria Gonzalez", "score": 0.9987, "start": 51, "end": 65 }
]
labels and threshold are optional and default per model. PhEye returns spans and
scores; it does not redact. Phileas and Philter call it and apply your policy’s strategy to
what comes back.
Connecting it
Philter points at the service with the PHEYE_ENDPOINT setting, used by policies that
perform named-entity detection.
Phileas takes a PhEye endpoint in the policy itself, through its named-entity filter. See the Phileas documentation for the field.
Choosing a lens
Larger lenses detect more and cost more to run. Start small and move up only if recall on your own data justifies it.
| Lens | Size | Image tag |
|---|---|---|
| English Names (Extra Small) | 90 MB (int8 ONNX) | pii_en_xsmall |
| English Names (Large) | 1.7 GB | pii_en_large |
| English Names (Medium) | 745 MB | pii_en_medium |
| English Names (Small) | 580 MB | pii_en_small |
Every lens has a -gpu variant, for example 1.3.0-pii_en_small-gpu. Use it when a GPU is
available; the CPU images run anywhere.
Full details for each, including entities detected and what it pairs with, are in the lens catalog.
Beyond English names
The published images cover more than the English family, including French person names, French medical text, medical conditions, and hospitals. Browse the tags on Docker Hub for the current set, and the pheye-pii-lenses repository for the catalog behind them.
Measuring before you trust it
A model’s score is a confidence, not a guarantee. Detection is probabilistic, and recall varies with your data far more than with the size of the lens.
Philter Scope scores a policy, model included, on precision and recall against gold-standard data. That is the way to choose between lenses honestly rather than picking the largest one.