{"id":28370267,"url":"https://github.com/freinold/gliner-api","last_synced_at":"2026-03-14T17:58:27.088Z","repository":{"id":295445895,"uuid":"989983846","full_name":"freinold/gliner-api","owner":"freinold","description":"A minimal FastAPI app serving GLiNER models","archived":false,"fork":false,"pushed_at":"2025-06-17T15:30:07.000Z","size":84,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-17T15:31:09.034Z","etag":null,"topics":["entity-detection","fastapi","gliner","ner"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/freinold.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-25T08:56:37.000Z","updated_at":"2025-06-17T15:30:12.000Z","dependencies_parsed_at":"2025-05-25T16:28:25.724Z","dependency_job_id":"89d2f171-7b3c-4b43-bbf2-1b7df94a23e3","html_url":"https://github.com/freinold/gliner-api","commit_stats":null,"previous_names":["freinold/gliner-api"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/freinold/gliner-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freinold%2Fgliner-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freinold%2Fgliner-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freinold%2Fgliner-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freinold%2Fgliner-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/freinold","download_url":"https://codeload.github.com/freinold/gliner-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freinold%2Fgliner-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261362050,"owners_count":23147321,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["entity-detection","fastapi","gliner","ner"],"created_at":"2025-05-29T06:08:41.290Z","updated_at":"2026-03-14T17:58:27.080Z","avatar_url":"https://github.com/freinold.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# gliner-api\n\n## Easily configurable API \u0026 frontend providing simple access to dynamic NER models\n\n[![Hugging Face Space](https://img.shields.io/badge/HuggingFace-Space-ffe720?logo=huggingface)](https://huggingface.co/spaces/bigscience/bloom-demo)\n[![Python 3.13.9](https://img.shields.io/badge/Python-3.13.9-3776ab?logo=python)](.python-version)\n[![GLiNER](https://img.shields.io/badge/GLiNER-0.2.21-e32e29)](https://github.com/urchade/GLiNER)\n[![License](https://img.shields.io/github/license/freinold/gliner-api)](https://github.com/freinold/gliner-api/blob/main/LICENSE)\n[![CodeQL](https://github.com/freinold/gliner-api/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/freinold/gliner-api/actions/workflows/github-code-scanning/codeql)\n[![Build Container Image](https://github.com/freinold/gliner-api/actions/workflows/docker-release.yml/badge.svg)](https://github.com/freinold/gliner-api/actions/workflows/docker-release.yml)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/freinold/gliner-api/badge)](https://scorecard.dev/viewer/?uri=github.com/freinold/gliner-api)\n\n  \u003cimg src=\"static/logo.png\" alt=\"GLiNER Logo\" width=\"200\"/\u003e\n\u003c/div\u003e\n\n## Features\n\n- **FastAPI** backend for serving GLiNER models (NER).\n- **Gradio** frontend (optional) for interactive use.\n- **Prometheus** metrics endpoint (`/metrics`).\n- **Configurable** via YAML, CLI, or environment variables.\n- **Docker** and **Docker Compose** support.\n- **ONNX** inference support (including quantized models).\n- **API key** authentication (optional).\n- **Custom metrics port** and enable/disable option for Prometheus metrics.\n\n---\n\n## Documentation\n\nFor detailed documentation, [see DeepWiki](https://deepwiki.com/freinold/GLiNER-API) (⚠️ AI-generated)\n\n---\n\n## Live Demo\n\nYou can try the live demo of the GLiNER API container in it's Huggingface Space: [GLiNER API Demo](https://huggingface.co/spaces/freinold/gliner-api).\n\nIt uses a minimally changed image to make it work in the Huggingface Space environment.\n\n---\n\n## Usage\n\n### Run with Docker\n\nYou can either build the container yourself or use a prebuilt image from GitHub Container Registry.\n\n#### Run prebuilt container (recommended)\n\n**CPU version:**\n\n```bash\ndocker run \\\n  -p 8080:8080 \\\n  -p 9090:9090 \\\n  -v $(pwd)/config.yaml:/app/config.yaml \\\n  -v $HOME/.cache/huggingface:/app/huggingface \\\n  ghcr.io/freinold/gliner-api:latest\n```\n\n**GPU version:**\n\n```bash\ndocker run \\\n  --gpus all \\\n  -p 8080:8080 \\\n  -p 9090:9090 \\\n  -v $(pwd)/config.yaml:/app/config.yaml \\\n  -v $HOME/.cache/huggingface:/app/huggingface \\\n  ghcr.io/freinold/gliner-api-gpu:latest\n```\n\n**Mounting volumes:**\n\n- `-v $(pwd)/config.yaml:/app/config.yaml` mounts your config file (edit as needed)\n- `-v $HOME/.cache/huggingface:/app/huggingface` mounts your Huggingface cache for faster model loading\n\n#### Build and run locally (CPU version)\n\n```bash\ndocker build \\\n  -f cpu.Dockerfile \\\n  --build-arg IMAGE_CREATED=\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" \\\n  --build-arg IMAGE_REVISION=\"$(git rev-parse HEAD)\" \\\n  --build-arg IMAGE_VERSION=\"$(git describe --tags --always)\" \\\n  -t gliner-api .\n\ndocker run --rm \\\n  -p 8080:8080 \\\n  -p 9090:9090 \\\n  -v $(pwd)/example_configs/general.yaml:/app/config.yaml \\\n  -v $HOME/.cache/huggingface:/app/huggingface \\\n  gliner-api\n```\n\n\u003cdetails\u003e\n\u003csummary\u003ePowerShell version\u003c/summary\u003e\n\n```powershell\ndocker build `\n  -f cpu.Dockerfile `\n  --build-arg IMAGE_CREATED=\"$(Get-Date -Format 'yyyy-MM-ddTHH:mm:ssZ')\" `\n  --build-arg IMAGE_REVISION=\"$(git rev-parse HEAD)\" `\n  --build-arg IMAGE_VERSION=\"$(git describe --tags --always)\" `\n  -t gliner-api .\n\ndocker run --rm `\n  -p 8080:8080 `\n  -p 9090:9090 `\n  -v \"$PWD/example_configs/general.yaml:/app/config.yaml\" `\n  -v \"$HOME/.cache/huggingface:/app/huggingface\" `\n  gliner-api\n```\n\n\u003c/details\u003e\n\n#### Build and run locally (GPU version)\n\n```bash\ndocker build \\\n  -f gpu.Dockerfile \\\n  --build-arg IMAGE_CREATED=\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" \\\n  --build-arg IMAGE_REVISION=\"$(git rev-parse HEAD)\" \\\n  --build-arg IMAGE_VERSION=\"$(git describe --tags --always)\" \\\n  -t gliner-api-gpu .\n\ndocker run --rm \\\n  --gpus all \\\n  -p 8080:8080 \\\n  -p 9090:9090 \\\n  -v $(pwd)/example_configs/general.yaml:/app/config.yaml \\\n  -v $HOME/.cache/huggingface:/app/huggingface \\\n  gliner-api-gpu\n```\n\n\u003cdetails\u003e\n\u003csummary\u003ePowerShell version\u003c/summary\u003e\n\n```powershell\ndocker build `\n  -f gpu.Dockerfile `\n  --build-arg IMAGE_CREATED=\"$(Get-Date -Format 'yyyy-MM-ddTHH:mm:ssZ')\" `\n  --build-arg IMAGE_REVISION=\"$(git rev-parse HEAD)\" `\n  --build-arg IMAGE_VERSION=\"$(git describe --tags --always)\" `\n  -t gliner-api-gpu .\n\ndocker run --rm `\n  --gpus all `\n  -p 8080:8080 `\n  -p 9090:9090 `\n  -v \"$PWD/example_configs/general.yaml:/app/config.yaml\" `\n  -v \"$HOME/.cache/huggingface:/app/huggingface\" `\n  gliner-api-gpu\n```\n\n\u003c/details\u003e\n\n---\n\n### Run with Docker Compose\n\nEdit [`cpu.compose.yaml`](cpu.compose.yaml) / [`gpu.compose.yaml`](gpu.compose.yaml) to select the config you want (see [`example_configs`](example_configs/)).\n\nThen run:\n\n```bash\n# For CPU version\ndocker compose -f cpu.compose.yaml up\n\n# For GPU version\ndocker compose -f gpu.compose.yaml up\n```\n\n---\n\n### Run the app directly\n\nBe sure to check the [installation instructions](#installation) first.\n\n```bash\nuv run main.py [OPTIONS]\n```\n\nOr with FastAPI CLI:\n\n```bash\nfastapi run main.py --host localhost\n```\n\n#### Run options\n\n```bash\nuv run main.py --help\n```\n\n| Option                  | Description                                               | Default                                          |\n| ----------------------- | --------------------------------------------------------- | ------------------------------------------------ |\n| `--use-case` / `--name` | Use case for the GLiNER model (application/domain)        | `general`                                        |\n| `--model-id`            | Huggingface model ID ([browse models][gliner-models])     | `knowledgator/gliner-x-base`                     |\n| `--onnx-enabled`        | Use ONNX for inference                                    | `False`                                          |\n| `--onnx-model-path`     | Path to ONNX model file                                   | `model.onnx`                                     |\n| `--default-entities`    | Default entities to detect                                | `['person', 'organization', 'location', 'date']` |\n| `--default-threshold`   | Default detection threshold                               | `0.5`                                            |\n| `--api-key`             | API key for authentication (if set, required in requests) | `null`                                           |\n| `--host`                | Host address                                              | `\"\"` (bind to all interfaces)                    |\n| `--port`                | Port                                                      | `8080`                                           |\n| `--metrics-enabled`     | Enable Prometheus metrics endpoint                        | `True`                                           |\n| `--metrics-port`        | Port for Prometheus metrics endpoint                      | `9090`                                           |\n| `--frontend-enabled`    | Enable Gradio frontend                                    | `True`                                           |\n\n[gliner-models]: https://huggingface.co/models?library=gliner\u0026sort=trending\n\n---\n\n## API \u0026 Frontend Endpoints\n\n| Description                  | Path       | Demo Link                                                     |\n| ---------------------------- | ---------- | ------------------------------------------------------------- |\n| Gradio Frontend (if enabled) | `/`        | [Frontend](https://freinold-gliner-api.hf.space/)             |\n| API Docs (Swagger)           | `/docs`    | [Swagger UI](https://freinold-gliner-api.hf.space/docs)       |\n| API Docs (ReDoc)             | `/redoc`   | [ReDoc](https://freinold-gliner-api.hf.space/redoc)           |\n| Prometheus Metrics           | `/metrics` | _(no public demo link; available on metrics port if enabled)_ |\n\n---\n\n## Example Request\n\n```bash\ncurl -X POST \"http://localhost:8080/api/invoke\" -H \"Content-Type: application/json\" -d '{\"text\": \"Steve Jobs founded Apple in Cupertino.\"}'\n```\n\n---\n\n## Installation\n\n**Prerequisites:**\n\n- Python 3.13.9\n- [uv](https://github.com/astral-sh/uv) (for dependency management)\n\n**Install dependencies:**\n\n```bash\n# CPU version\nuv sync --extra cpu [--extra frontend]\n\n# GPU version\nuv sync --extra gpu [--extra frontend]\n```\n\nThe frontend is optional, but encouraged for interactive use.\n\n**Install from source:**\n\n```bash\ngit clone https://github.com/freinold/gliner-api.git\ncd gliner-api\nuv sync --extra cpu  # or --extra gpu\n```\n\n---\n\n## Configuration\n\nYou can configure the app via:\n\n- `config.yaml` (default, see `example_configs/`)\n- CLI options (see above)\n- Environment variables (prefix: `GLINER_API_`)\n\nExample configs:\n\n- `example_configs/general.yaml` (default NER)\n- `example_configs/pii.yaml` (PII detection)\n- `example_configs/medical.yaml` (medical NER)\n- `example_configs/general_onnx.yaml` (ONNX inference)\n- `example_configs/general_onnx_quantized.yaml` (quantized ONNX)\n\n---\n\n## Used Frameworks \u0026 Libraries\n\n- [FastAPI](https://fastapi.tiangolo.com/) (API backend)\n- [Gradio](https://gradio.app/) (optional frontend)\n- [Uvicorn](https://www.uvicorn.org/) (ASGI server)\n- [Prometheus Client](https://github.com/prometheus/client_python) (metrics)\n- [Huggingface Hub](https://huggingface.co/docs/huggingface_hub) (model loading)\n- [PyTorch](https://pytorch.org/) (CPU/GPU inference)\n- [ONNX](https://onnx.ai/) (optional, for ONNX models)\n- [uv](https://github.com/astral-sh/uv) (dependency management)\n\n---\n\n## License\n\nSee [LICENSE](LICENSE).\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreinold%2Fgliner-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreinold%2Fgliner-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreinold%2Fgliner-api/lists"}