finalign / DEPLOY.md
pdmdp's picture
Upload 22 files
c0f3416 verified
|
Raw History Blame Contribute Delete
3.22 kB

Run the demo

The application uses Gradio and is configured for a Hugging Face ZeroGPU Space. It uses no paid inference API. ZeroGPU has a queue and a daily allowance; a free account can reach its limit during indexing or repeated searches.

Upload to Hugging Face

Create a public Space with Gradio, the Blank template and ZeroGPU hardware. Use the MIT license for the code. No storage subscription is required.

Upload the contents of this directory to the Space root. app.py, requirements.txt, packages.txt and this README.md belong at the root; preserve the finalign/ and data/ directories. Do not upload the outer delivery ZIP as a single file. The ZIP inside data/ is an application asset and should stay compressed.

The initial bundle needs data/fiqa-corpus.zip. It contains the full corpus, lexical index, passage IDs and model revisions, but no completed dense embeddings. It is generated with:

python -m pip install -r requirements.txt
python build_index.py --corpus-only --output data/fiqa-corpus

Java 11 or newer is needed for Terrier. Hugging Face installs it from packages.txt. Model files are downloaded at startup, so the first launch takes longer than subsequent searches.

Prepare the dense index once

  1. Open the Space and sign in with its owner account using the login button.
  2. Click Prepare / continue index. Each call encodes a bounded batch and checkpoints completed passages. Continue until all 66,113 passages are encoded. Calls use the free GPU allowance; if it runs out, wait for its reset and resume. Availability and total preparation time depend on the shared hardware.
  3. Download the resulting fiqa-index.zip.
  4. In the Space’s Files tab, open data/ and upload that ZIP without unpacking it. This commits the completed index, preserving it across rebuilds. Until this upload, progress lives on the Space’s temporary disk and could be lost if the container is replaced.

When data/fiqa-index.zip is present, the app starts directly in search mode. Visitors do not run indexing. The corpus ZIP can remain in the repository; the completed index takes precedence.

Only the owner can invoke the preparation callback. OAuth requests basic profile access, not repository write access. No token needs to be pasted into the app or code.

Build on another GPU

An existing CUDA environment can build the complete archive in one run:

python build_index.py --device cuda --output data/fiqa-index

Upload data/fiqa-index.zip with the application to skip Space preparation. A CPU or Apple MPS build is also supported, but full-corpus encoding can take hours on a laptop.

Local checks

python -m unittest discover -s tests -v
python app.py

FINALIGN_INDEX_DIR may point to an unpacked index. FINALIGN_DEVICE defaults to CPU locally and CUDA in a Space. FINALIGN_ENCODER_ONLY=1 skips downloading Qwen and monoT5 for a local BGE/BM25 smoke check; expansion and reranking controls are disabled in that mode.

The Space’s GPU settings determine the cost. The code does not switch hardware or buy credits. Queueing failures leave the BM25 result visible and can be retried later.