BLIP + two-tier RAG bird identification service built with FastAPI.
图像 + 地点/日期/栖息地
→ Taxonomy shortlist（上下文检索）
→ BLIP caption + 候选打分 → Top-k
→ 轻量 RAG（始终）：final = BLIP × range × season × habitat → 重排
→ 无深度触发条件 → 直接返回
→ 否则：深度 RAG 检索 corpus chunks → LLM 生成 Top-5 + citations + 追问
深度 RAG 触发：BLIP top1 < 0.6、分数接近、生态先验与 BLIP 冲突、弱分布先验、图片质量差、用户要求解释。
cd /home/hcc/bird-agent
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .envRecommended .env:
VISION_PROVIDER=blip_local
BLIP_MODEL_PATH=/path/to/inat-blip-checkpoint
OPENAI_API_KEY=your-key
AGENT_MODEL=gpt-4.1-mini
RETRIEVAL_EMBEDDING_ENABLED=true
RAG_CORPUS_PATH=data/rag/corpus.jsonl
BLIP_UNCERTAIN_THRESHOLD=0.60Build RAG corpus (optional; auto-built from taxonomy on first deep RAG run):
python scripts/build_rag_corpus.py \
--taxonomy data/taxonomy/birds_us_unified.json \
--output data/rag/corpus.jsonluvicorn BirdClaw.main:app --reload --port 8000Web UI: http://127.0.0.1:8000/
curl -X POST "http://127.0.0.1:8000/identify" \
-F "image=@/path/to/bird.jpg" \
-F "location=Santa Barbara, California, USA" \
-F "date=2026-01-18" \
-F "habitat=coastal wetland"Response includes best_match, top_k, reasoning, citations, retrieved_chunks, follow_up.
| Variable | Purpose |
|---|---|
BLIP_UNCERTAIN_THRESHOLD |
BLIP top1 低于此值触发深度 RAG |
RAG_DEEP_MARGIN |
Top1−Top2 低于此值触发深度 RAG |
RAG_PRIOR_CONFLICT_THRESHOLD |
分布先验低于此值视为冲突 |
RETRIEVAL_TOP_K |
taxonomy shortlist 大小 |
RAG_TOP_K |
深度 RAG 检索 chunk 数量 |
RAG_CORPUS_PATH |
知识库 JSONL 路径 |
Taxonomy loading order: TAXONOMY_PATH → birds_us_unified.json → birds_unified.json → seed/sample fallbacks.
pytest -q