AlpinDale/foidfinder

选用指南

AI 根据 README 整理 · 2026/10/28 22:01:30

使用方式

通过命令行工具或HTTP API使用，支持Docker部署。

查看 README 依据

## Docker (NVIDIA) Requires the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/) and a driver for CUDA 13.0 (580 or newer). ```sh docker compose up -d --build # http://127.0.0.1:8000 ``` On first start the container downloads the int8 checkpoint [alpindale/PixAI-v1.0-INT8](https://huggingface.co/alpindale/PixAI-v1.0-INT8) (0.6 GB) into the `models` volume. The kernels are compiled at build time for the `CUDA_ARCHS` build argument (default `8.9`, add `8.6` for RTX 30-series

sandboxing CSP. A compromised GPU host can return wrong tags but cannot serve pages on your domain. It does see the uploaded images. ## From source ```sh uv sync --extra mlx # Apple Silicon uv sync --extra cuda # NVIDIA, needs nvcc (CUDA 12.8+) to build the kernels on first use (cd web && npm ci && npm run build) # builds the UI into foidfinder/webui/ uv run foidfinder download # official checkpoint into models/pixai-tagger-v1.0 uv run foidfinder serve # http://127.0.0.1:8000

uv run foidfinder tag a.jpg b.png # --json prints one result per line uv run foidfinder bench a.jpg ``` `foidfinder convert <dir>` writes the int8 checkpoint for the CUDA backend, with `config.json` and a model card, ready for `hf upload`. The CUDA backend also loads the official checkpoint and quantizes it at startup, which takes longer and needs 3.3 GB of VRAM during loading instead of 0.9 GB. The MLX backend needs the official checkpoint. ## Configuration Each option is set by an environment variable or the matching `foidfinder serve` flag.

部署要求

NVIDIA GPU需支持CUDA 13.0驱动和NVIDIA Container Toolkit（Docker方式），或从源码构建需CUDA 12.8+；Apple Silicon需MLX后端。

查看 README 依据

## Docker (NVIDIA) Requires the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/) and a driver for CUDA 13.0 (580 or newer). ```sh docker compose up -d --build # http://127.0.0.1:8000 ``` On first start the container downloads the int8 checkpoint [alpindale/PixAI-v1.0-INT8](https://huggingface.co/alpindale/PixAI-v1.0-INT8) (0.6 GB) into the `models` volume. The kernels are compiled at build time for the `CUDA_ARCHS` build argument (default `8.9`, add `8.6` for RTX 30-series

sandboxing CSP. A compromised GPU host can return wrong tags but cannot serve pages on your domain. It does see the uploaded images. ## From source ```sh uv sync --extra mlx # Apple Silicon uv sync --extra cuda # NVIDIA, needs nvcc (CUDA 12.8+) to build the kernels on first use (cd web && npm ci && npm run build) # builds the UI into foidfinder/webui/ uv run foidfinder download # official checkpoint into models/pixai-tagger-v1.0 uv run foidfinder serve # http://127.0.0.1:8000

已知限制

上传图片限制32MB或64百万像素，队列满时返回503错误。

查看 README 依据

| `POST /api/tag` (image file as the body) | `rating`, `tags` by category (at PixAI's per-category thresholds, sorted by score), `candidates` (up to 3 below-threshold characters and series), `image` size, `timings_ms` | | `GET /api/info` | model, backend, device, upload limits | | `GET /api/health` | `{"status": "ok"}` once the model is loaded | Errors have the form `{"error": {"code": ..., "message": ...}}`. | Status | Cause | |---|---| | 400 | empty body | | 413 | file over 32 MB or image over 64 megapixels | | 415 | not an image | | 422 | damaged image |

| 503 | queue full; retry after `Retry-After` seconds | Uploads are decoded in memory and never written to disk. ## Accuracy and speed Both backends keep the 72×72 patch tokens in window order (3×3 windows of 24×24), so windowed attention needs no partition or merge transposes. The MLX backend matches the official implementation within 1e-5 in fp32 and 0.003 in fp16. The CUDA backend quantizes every transformer GEMM to int8. Activations are rotated by a Hadamard matrix and scaled per