shaochenjie/bird-harrier-retriever

BIRD Harrier field retriever (schema96 checkpoint)

This repository packages the original BIRD column-retrieval fine-tune used by the bird-harrier600m-20261003 service. It is not the improved v2 checkpoint, the joint field/entity model, or the unmodified upstream Harrier model.

This is a public evaluation-delivery repository, published with the owner's approval on 2026-10-22. Public availability is not a separate license grant. The upstream model is microsoft/harrier-oss-v1-0.6b, whose model card declares MIT. Its repository does not include a separate LICENSE file; see UPSTREAM_NOTICE.txt. No new license grant for the fine-tuning work is claimed by this model card. No training rows, database files, API credentials, optimizer states or development predictions are included.

Exact encoding contract

Property	Frozen value
Query text	Question only, no instruction prefix
Document text	table.column; the BIRD caller lowercases it
Query maximum length	128 tokens
Document maximum length	32 tokens
Padding	Right
Pooling	Attention-mask-weighted mean of final hidden states
Projection	None
Output	1024-dimensional, L2-normalized float32 vectors
GPU computation	bfloat16, model in evaluation mode
Similarity	Dot product of normalized vectors
BIRD field threshold	score >= 0.65, within the question's database

Do not use the upstream last-token pooling / instruction-prefix recipe. This fine-tune was trained and evaluated with the contract above. Standard feature-extraction pipelines return token vectors and do not implement this contract automatically. chat_template.jinja is a preserved tokenizer asset; the encoder does not apply a chat template.

Training provenance and limitations

The saved training configuration specifies BIRD train question/column pairs, question-only queries, table.column positive passages, mean pooling, full fine-tuning without LoRA/projection, five epochs, learning rate 2e-5, batch size 4, gradient accumulation 4, and contrastive temperature 0.02. It points to an empty evaluation file, rather than dev data. This describes the saved configuration, not a new independent audit of every training example.

This is the original pairwise training version, not the later multi-positive training correction. Development-set analysis was used in system design and threshold selection; this is not a claim of a completely untouched dev set.

The downstream system containing this encoder scored 1152/1534 (75.10%) on its frozen BIRD dev snapshot. That is a full SQL pipeline score, not an embedding model accuracy or an official test score. Other components include Qwen embeddings, an external LLM, retrieval, nine candidate slots and SQL checkers. Inference never needs target-question Gold SQL.

Verify the downloaded files

Download the entire repository at a fixed commit revision. From its directory:

python verify_files.py

model_manifest.json contains the exact hashes of the six runtime model files. The main weight is 1,192,133,232 bytes and has SHA256: 50b590d2c598a43d4517fa7bbf20061c21777e1cb12514506f28f43d004e055d.

Run locally (no external embedding API required)

Use a separate Python 3.12 environment and install requirements.txt. The reference deployment used PyTorch 2.10.0 and CUDA 12.8; the evaluator must confirm driver compatibility. Installing a different torch/CUDA combination requires a parity check, not an assumption of identical vectors.

python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
export API_TOKEN="$(.venv/bin/python -c 'import secrets; print(secrets.token_urlsafe(32))')"
bash serve.sh

Keep the token in the evaluator's environment/secret store and use it for client requests. The command defaults to loopback 127.0.0.1:8080, CUDA, one worker and no HTTP access log. Set MODEL_PATH, DEVICE, HOST or PORT explicitly when needed. CPU mode uses float32 and is intended for functional checks; bitwise GPU parity is not promised. No model downloads are performed during service startup.

Endpoints:

• GET /health (no authentication), requiring loaded=true before inference.
• GET /v1/models (Bearer token).
• POST /v1/embeddings (Bearer token), for example:

{"model":"bird-harrier600m-20261003","input_type":"query","input":["How many schools are in Riverside?"]}

For fields, use input_type: "document" and inputs such as schools.school. Maximum batch is 32 nonempty strings and 8192 encoded tokens. Only float encoding is supported. Do not log request bodies in reverse proxies.

The service source is copied from the frozen deployed encoder, with its authentication and pooling unchanged. serve.sh sets writable caches and a username to support container UIDs without a passwd entry.

Optional container

docker build -t bird-harrier-local .
docker run --rm --gpus all --env-file evaluator-secrets.env \
  -p 127.0.0.1:8080:8080 bird-harrier-local

evaluator-secrets.env contains only a dedicated API_TOKEN (minimum 32 ASCII characters). Do not commit that file. The image contains the model and starts the same encoder. The Docker recipe must be tested on the evaluator's CUDA environment; a recipe alone is not evidence that an image has been validated.

Qwen embedding is a separate dependency

This repository does not replace Qwen3-Embedding-0.6B used for value/few-shot retrieval. Its checkpoint and its distinct last-token pooling recipe must also be frozen in the full submission package. Do not apply Harrier mean pooling to that second model.