From 3960da75cc84ead4bfe6aebaeff917c3e88d2803 Mon Sep 17 00:00:00 2001 From: Evgeniya Sukhodolskaya Date: Sat, 4 Jul 2026 20:40:28 +0200 Subject: [PATCH 1/2] docs: fix README staleness; align embedding defaults to text-embedding-3-small (1024/1536) - Drop stale version numbers from provider badges. - Update qdrant-labs clone URLs and frontend GRAPHRAG_API_URL note. - Document that openai_api_key is required per request. - Trim the ingestion note and Vercel section. - config.py and .env.example default to text-embedding-3-small, dims 1024/1536. Co-Authored-By: Claude Opus 4.8 --- .env.example | 8 ++++---- README.md | 32 +++++++++++++++++-------------- src/biomedical_graphrag/config.py | 6 +++--- 3 files changed, 25 insertions(+), 21 deletions(-) diff --git a/.env.example b/.env.example index 9ecfa4b..d8d89a2 100644 --- a/.env.example +++ b/.env.example @@ -14,9 +14,9 @@ NEO4J__DATABASE=neo4j QDRANT__URL=your_qdrant_url_here QDRANT__API_KEY=your_qdrant_api_key_here QDRANT__COLLECTION_NAME=biomedical_papers -QDRANT__EMBEDDING_MODEL=text-embedding-3-large -QDRANT__EMBEDDING_DIMENSION=1536 -QDRANT__RERANKER_EMBEDDING_DIMENSION=3072 +QDRANT__EMBEDDING_MODEL=text-embedding-3-small +QDRANT__EMBEDDING_DIMENSION=1024 +QDRANT__RERANKER_EMBEDDING_DIMENSION=1536 QDRANT__ESTIMATE_BM25_AVG_LEN_ON_X_DOCS=300 QDRANT__CLOUD_INFERENCE=true @@ -26,4 +26,4 @@ PUBMED__EMAIL=your_email@example.com # JSON Data Paths (optional — defaults are data/pubmed_dataset.json and data/gene_dataset.json) JSON_DATA__PUBMED_JSON_PATH=data/pubmed_dataset.json -JSON_DATA__GENE_JSON_PATH=data/gene_dataset.json +JSON_DATA__GENE_JSON_PATH=data/gene_dataset.json \ No newline at end of file diff --git a/README.md b/README.md index 49816ac..883a890 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@ -[![Qdrant](https://img.shields.io/badge/Qdrant-1.15.1-5A31F4?logo=qdrant&logoColor=white)](https://qdrant.tech/) -[![Neo4j](https://img.shields.io/badge/Neo4j-5.28.2-008CC1?logo=neo4j&logoColor=white)](https://neo4j.com/) -[![OpenAI](https://img.shields.io/badge/OpenAI-2.3.0-412991?logo=openai&logoColor=white)](https://openai.com/) +[![Qdrant](https://img.shields.io/badge/Qdrant-5A31F4?logo=qdrant&logoColor=white)](https://qdrant.tech/) +[![Neo4j](https://img.shields.io/badge/Neo4j-008CC1?logo=neo4j&logoColor=white)](https://neo4j.com/) +[![OpenAI](https://img.shields.io/badge/OpenAI-412991?logo=openai&logoColor=white)](https://openai.com/) @@ -105,7 +105,7 @@ biomedical-graphrag/ 1. Clone the repository: ```bash - git clone git@github.com:thierrypdamiba/biomedical-graphrag.git + git clone git@github.com:qdrant-labs/biomedical-graphrag.git cd biomedical-graphrag ``` @@ -156,9 +156,9 @@ NEO4J__DATABASE=neo4j QDRANT__URL=http://localhost:6333 QDRANT__API_KEY=your_qdrant_api_key QDRANT__COLLECTION_NAME=biomedical_papers -QDRANT__EMBEDDING_MODEL=text-embedding-3-large -QDRANT__EMBEDDING_DIMENSION=1536 -QDRANT__RERANKER_EMBEDDING_DIMENSION=3072 +QDRANT__EMBEDDING_MODEL=text-embedding-3-small +QDRANT__EMBEDDING_DIMENSION=1024 +QDRANT__RERANKER_EMBEDDING_DIMENSION=1536 QDRANT__ESTIMATE_BM25_AVG_LEN_ON_X_DOCS=300 QDRANT__CLOUD_INFERENCE=false @@ -227,9 +227,7 @@ Notes: - This project uses OpenAI embeddings **Matryoshka Representation Learning (MRL)** feature: - `QDRANT__EMBEDDING_DIMENSION` is the prefix dimension used for **retrieval** (stored in Qdrant as the `Dense` vector). - `QDRANT__RERANKER_EMBEDDING_DIMENSION` is the (larger) prefix dimension used for **reranking** (stored in Qdrant as the `Reranker` vector). -- `make ingest-qdrant-data` currently recreates the collection each run (see `qdrant_ingestion.py`). - If you don't want that, change `recreate=True` to `False`. There's also an `only_new` parameter which defaults to `True`, so we ingest only papers whose PMID is not already - present in the collection. Set `only_new=False` if you'd prefer to overwrite existing points or on a clean ingestion (then it should be `False`!) +- `make ingest-qdrant-data` recreates the collection each run (`recreate=True` in `qdrant_ingestion.py`); set it to `False` to keep existing points. The `only_new` flag (default `True`) skips PMIDs already in the collection. - The collection is configured by default with **scalar quantization** (compressed dense vectors). - `QDRANT__CLOUD_INFERENCE=true` enables **Qdrant Cloud Inference** when embeddings are computed by Qdrant Cloud. - `QDRANT__ESTIMATE_BM25_AVG_LEN_ON_X_DOCS` controls how many documents are sampled to estimate the average abstract length used by **BM25**. This helps calibrate BM25-based scoring when using dense+BM25 hybrid retrieval. @@ -290,12 +288,14 @@ make run-api ```bash curl -X POST http://localhost:8765/api/graphrag-query \ -H "Content-Type: application/json" \ - -d '{"query": "What genes are associated with breast cancer?", "limit": 5}' + -d '{"query": "What genes are associated with breast cancer?", "limit": 5, "openai_api_key": "sk-..."}' ``` +> `openai_api_key` is required on every request. It is used transiently and never stored or logged. A rejected key returns HTTP 401 with `detail: openai_key_rejected`. + ### Frontend -The frontend is maintained in a separate repository: **[biomedical-graphrag-frontend](https://github.com/thierrypdamiba/biomedical-graphrag-frontend)** +The frontend is maintained in a separate repository: **[biomedical-graphrag-frontend](https://github.com/qdrant-labs/biomedical-graphrag-frontend)** The quickest way to run it locally: @@ -307,13 +307,13 @@ make run-frontend Or manually: ```bash -git clone https://github.com/thierrypdamiba/biomedical-graphrag-frontend.git +git clone https://github.com/qdrant-labs/biomedical-graphrag-frontend.git cd biomedical-graphrag-frontend pnpm install pnpm dev ``` -The frontend connects to the hosted backend at `https://biomedical-graphrag-9qqm.onrender.com` by default, or you can point it to a local backend via `GRAPHRAG_API_URL=http://localhost:8765`. +The frontend requires `GRAPHRAG_API_URL` to point at this backend. ### Docker @@ -330,6 +330,10 @@ docker run --rm -p 8765:8765 --env-file .env biomedical-graphrag:latest curl http://localhost:8765/health ``` +### Deploy to Vercel + +Runs as a container via `Dockerfile.vercel`. + ### Troubleshooting - **Make fails immediately with ".env file is missing"** diff --git a/src/biomedical_graphrag/config.py b/src/biomedical_graphrag/config.py index a6f4604..6a33e21 100644 --- a/src/biomedical_graphrag/config.py +++ b/src/biomedical_graphrag/config.py @@ -32,13 +32,13 @@ class QdrantSettings(BaseModel): default="biomedical_papers", description="Collection name for Qdrant instance" ) embedding_model: str = Field( - default="text-embedding-3-large", description="OpenAI embedding model to use" + default="text-embedding-3-small", description="OpenAI embedding model to use" ) embedding_dimension: int = Field( - default=1536, description="Dimension of the OpenAI embedding for retrieval (using OpenAI's MRL)" + default=1024, description="Dimension of the OpenAI embedding for retrieval (using OpenAI's MRL)" ) reranker_embedding_dimension: int = Field( - default=3072, + default=1536, description="Dimension of the OpenAI embedding for reranking (using OpenAI's MRL)", ) estimate_bm25_avg_len_on_x_docs: int = Field( From 54c4e87d1cc5f29d57688a382dc7e745e2db686e Mon Sep 17 00:00:00 2001 From: Evgeniya Sukhodolskaya Date: Sat, 4 Jul 2026 20:51:04 +0200 Subject: [PATCH 2/2] test: update Qdrant default assertions to text-embedding-3-small (1024/1536) Co-Authored-By: Claude Opus 4.8 --- tests/integration/test_config.py | 12 ++++++------ tests/integration/test_databases.py | 6 +++--- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/tests/integration/test_config.py b/tests/integration/test_config.py index 88b0055..6261f55 100644 --- a/tests/integration/test_config.py +++ b/tests/integration/test_config.py @@ -22,9 +22,9 @@ def test_settings_creation_with_defaults() -> None: qdrant_settings = QdrantSettings() assert qdrant_settings.url == "http://localhost:6333" assert qdrant_settings.collection_name == "biomedical_papers" - assert qdrant_settings.embedding_model == "text-embedding-3-large" - assert qdrant_settings.embedding_dimension == 1536 - assert qdrant_settings.reranker_embedding_dimension == 3072 + assert qdrant_settings.embedding_model == "text-embedding-3-small" + assert qdrant_settings.embedding_dimension == 1024 + assert qdrant_settings.reranker_embedding_dimension == 1536 assert qdrant_settings.estimate_bm25_avg_len_on_x_docs == 300 assert qdrant_settings.cloud_inference is False @@ -76,9 +76,9 @@ def test_qdrant_settings_validation() -> None: assert qdrant_settings.url == "http://localhost:6333" assert qdrant_settings.collection_name == "biomedical_papers" - assert qdrant_settings.embedding_model == "text-embedding-3-large" - assert qdrant_settings.embedding_dimension == 1536 - assert qdrant_settings.reranker_embedding_dimension == 3072 + assert qdrant_settings.embedding_model == "text-embedding-3-small" + assert qdrant_settings.embedding_dimension == 1024 + assert qdrant_settings.reranker_embedding_dimension == 1536 assert qdrant_settings.estimate_bm25_avg_len_on_x_docs == 300 assert qdrant_settings.cloud_inference is False assert qdrant_settings.api_key.get_secret_value() == "" diff --git a/tests/integration/test_databases.py b/tests/integration/test_databases.py index 2670cad..7b61db4 100644 --- a/tests/integration/test_databases.py +++ b/tests/integration/test_databases.py @@ -125,9 +125,9 @@ def test_qdrant_settings_validation(self) -> None: assert qdrant_settings.url == "http://localhost:6333" assert qdrant_settings.collection_name == "biomedical_papers" - assert qdrant_settings.embedding_model == "text-embedding-3-large" - assert qdrant_settings.embedding_dimension == 1536 - assert qdrant_settings.reranker_embedding_dimension == 3072 + assert qdrant_settings.embedding_model == "text-embedding-3-small" + assert qdrant_settings.embedding_dimension == 1024 + assert qdrant_settings.reranker_embedding_dimension == 1536 assert qdrant_settings.estimate_bm25_avg_len_on_x_docs == 300 assert qdrant_settings.cloud_inference is False