{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Quick Start in 30s" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "# install this if you areusing colab\n", "! pip install leann" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Build the index" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "INFO: Registering backend 'hnsw'\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "/Users/yichuan/Desktop/code/LEANN/leann/.venv/lib/python3.11/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n", " from .autonotebook import tqdm as notebook_tqdm\n", "INFO:sentence_transformers.SentenceTransformer:Load pretrained SentenceTransformer: facebook/contriever\n", "WARNING:sentence_transformers.SentenceTransformer:No sentence-transformers model found with name facebook/contriever. Creating a new one with mean pooling.\n", "Writing passages: 100%|██████████| 5/5 [00:00<00:00, 27887.66chunk/s]\n", "Batches: 100%|██████████| 1/1 [00:00<00:00, 13.51it/s]\n", "WARNING:leann_backend_hnsw.hnsw_backend:Converting data to float32, shape: (5, 768)\n", "INFO:leann_backend_hnsw.hnsw_backend:INFO: Converting HNSW index to CSR-pruned format...\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "M: 64 for level: 0\n", "Starting conversion: knowledge.index -> knowledge.csr.tmp\n", "[0.00s] Reading Index HNSW header...\n", "[0.00s] Header read: d=768, ntotal=5\n", "[0.00s] Reading HNSW struct vectors...\n", " Reading vector (dtype=, fmt='d')... Count=6, Bytes=48\n", "[0.00s] Read assign_probas (6)\n", " Reading vector (dtype=, fmt='i')... Count=7, Bytes=28\n", "[0.11s] Read cum_nneighbor_per_level (7)\n", " Reading vector (dtype=, fmt='i')... Count=5, Bytes=20\n", "[0.21s] Read levels (5)\n", "[0.30s] Probing for compact storage flag...\n", "[0.30s] Found compact flag: False\n", "[0.30s] Compact flag is False, reading original format...\n", "[0.30s] Probing for potential extra byte before non-compact offsets...\n", "[0.30s] Found and consumed an unexpected 0x00 byte.\n", " Reading vector (dtype=, fmt='Q')... Count=6, Bytes=48\n", "[0.30s] Read offsets (6)\n", "[0.40s] Attempting to read neighbors vector...\n", " Reading vector (dtype=, fmt='i')... Count=320, Bytes=1280\n", "[0.40s] Read neighbors (320)\n", "[0.50s] Read scalar params (ep=4, max_lvl=0)\n", "[0.50s] Checking for storage data...\n", "[0.50s] Found storage fourcc: 49467849.\n", "[0.50s] Converting to CSR format...\n", "[0.50s] Conversion loop finished. \n", "[0.50s] Running validation checks...\n", " Checking total valid neighbor count...\n", " OK: Total valid neighbors = 20\n", " Checking final pointer indices...\n", " OK: Final pointers match data size.\n", "[0.50s] Deleting original neighbors and offsets arrays...\n", " CSR Stats: |data|=20, |level_ptr|=10\n", "[0.59s] Writing CSR HNSW graph data in FAISS-compatible order...\n", " Pruning embeddings: Writing NULL storage marker.\n", "[0.69s] Conversion complete.\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:leann_backend_hnsw.hnsw_backend:✅ CSR conversion successful.\n", "INFO:leann_backend_hnsw.hnsw_backend:INFO: Replaced original index with CSR-pruned version at 'knowledge.index'\n" ] } ], "source": [ "from leann.api import LeannBuilder\n", "\n", "builder = LeannBuilder(backend_name=\"hnsw\")\n", "builder.add_text(\"C# is a powerful programming language and it is good at game development\")\n", "builder.add_text(\"Python is a powerful programming language and it is good at machine learning tasks\")\n", "builder.add_text(\"Machine learning transforms industries\")\n", "builder.add_text(\"Neural networks process complex data\")\n", "builder.add_text(\"Leann is a great storage saving engine for RAG on your MacBook\")\n", "builder.build_index(\"knowledge.leann\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Search with real-time embeddings" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "INFO:leann.api:🔍 LeannSearcher.search() called:\n", "INFO:leann.api: Query: 'programming languages'\n", "INFO:leann.api: Top_k: 2\n", "INFO:leann.api: Additional kwargs: {}\n", "INFO:leann.embedding_server_manager:Port 5557 has incompatible server, trying next port...\n", "INFO:leann.embedding_server_manager:Port 5558 has incompatible server, trying next port...\n", "INFO:leann.embedding_server_manager:Port 5559 has incompatible server, trying next port...\n", "INFO:leann.embedding_server_manager:Using port 5560 instead of 5557\n", "INFO:leann.embedding_server_manager:Starting embedding server on port 5560...\n", "INFO:leann.embedding_server_manager:Command: /Users/yichuan/Desktop/code/LEANN/leann/.venv/bin/python -m leann_backend_hnsw.hnsw_embedding_server --zmq-port 5560 --model-name facebook/contriever --passages-file knowledge.leann.meta.json\n", "huggingface/tokenizers: The current process just got forked, after parallelism has already been used. Disabling parallelism to avoid deadlocks...\n", "To disable this warning, you can either:\n", "\t- Avoid using `tokenizers` before the fork if possible\n", "\t- Explicitly set the environment variable TOKENIZERS_PARALLELISM=(true | false)\n", "INFO:leann.embedding_server_manager:Server process started with PID: 4574\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "[read_HNSW - CSR NL v4] Reading metadata & CSR indices (manual offset)...\n", "[read_HNSW NL v4] Read levels vector, size: 5\n", "[read_HNSW NL v4] Reading Compact Storage format indices...\n", "[read_HNSW NL v4] Read compact_level_ptr, size: 10\n", "[read_HNSW NL v4] Read compact_node_offsets, size: 6\n", "[read_HNSW NL v4] Read entry_point: 4, max_level: 0\n", "[read_HNSW NL v4] Read storage fourcc: 0x6c6c756e\n", "[read_HNSW NL v4 FIX] Detected FileIOReader. Neighbors size field offset: 326\n", "[read_HNSW NL v4] Reading neighbors data into memory.\n", "[read_HNSW NL v4] Read neighbors data, size: 20\n", "[read_HNSW NL v4] Finished reading metadata and CSR indices.\n", "INFO: Skipping external storage loading, since is_recompute is true.\n", "INFO: Registering backend 'hnsw'\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:leann.embedding_server_manager:Embedding server is ready!\n", "INFO:leann.api: Launching server time: 1.078078269958496 seconds\n", "INFO:leann.embedding_server_manager:Existing server process (PID 4574) is compatible\n", "INFO:sentence_transformers.SentenceTransformer:Load pretrained SentenceTransformer: facebook/contriever\n", "WARNING:sentence_transformers.SentenceTransformer:No sentence-transformers model found with name facebook/contriever. Creating a new one with mean pooling.\n", "INFO:leann.api: Generated embedding shape: (1, 768)\n", "INFO:leann.api: Embedding time: 2.9307072162628174 seconds\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "ZmqDistanceComputer initialized: d=768, metric=0\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:leann.api: Search time: 0.27327895164489746 seconds\n", "INFO:leann.api: Backend returned: labels=2 results\n", "INFO:leann.api: Processing 2 passage IDs:\n", "INFO:leann.api: 1. passage_id='0' -> SUCCESS: C# is a powerful programming language and it is good at game development...\n", "INFO:leann.api: 2. passage_id='1' -> SUCCESS: Python is a powerful programming language and it is good at machine learning tasks...\n", "INFO:leann.api: Final enriched results: 2 passages\n" ] }, { "data": { "text/plain": [ "[SearchResult(id='0', score=np.float32(0.9874103), text='C# is a powerful programming language and it is good at game development', metadata={}),\n", " SearchResult(id='1', score=np.float32(0.8922168), text='Python is a powerful programming language and it is good at machine learning tasks', metadata={})]" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from leann.api import LeannSearcher\n", "\n", "searcher = LeannSearcher(\"knowledge.leann\")\n", "results = searcher.search(\"programming languages\", top_k=2)\n", "results" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Chat with LEANN using retrieved results" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "INFO:leann.chat:Attempting to create LLM of type='hf' with model='Qwen/Qwen3-0.6B'\n", "INFO:leann.chat:Initializing HFChat with model='Qwen/Qwen3-0.6B'\n", "INFO:leann.chat:MPS is available. Using Apple Silicon GPU.\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "[read_HNSW - CSR NL v4] Reading metadata & CSR indices (manual offset)...\n", "[read_HNSW NL v4] Read levels vector, size: 5\n", "[read_HNSW NL v4] Reading Compact Storage format indices...\n", "[read_HNSW NL v4] Read compact_level_ptr, size: 10\n", "[read_HNSW NL v4] Read compact_node_offsets, size: 6\n", "[read_HNSW NL v4] Read entry_point: 4, max_level: 0\n", "[read_HNSW NL v4] Read storage fourcc: 0x6c6c756e\n", "[read_HNSW NL v4 FIX] Detected FileIOReader. Neighbors size field offset: 326\n", "[read_HNSW NL v4] Reading neighbors data into memory.\n", "[read_HNSW NL v4] Read neighbors data, size: 20\n", "[read_HNSW NL v4] Finished reading metadata and CSR indices.\n", "INFO: Skipping external storage loading, since is_recompute is true.\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "INFO:leann.api:🔍 LeannSearcher.search() called:\n", "INFO:leann.api: Query: 'Compare the two retrieved programming languages and tell me their advantages.'\n", "INFO:leann.api: Top_k: 2\n", "INFO:leann.api: Additional kwargs: {}\n", "INFO:leann.embedding_server_manager:Port 5557 has incompatible server, trying next port...\n", "INFO:leann.embedding_server_manager:Port 5558 has incompatible server, trying next port...\n", "INFO:leann.embedding_server_manager:Port 5559 has incompatible server, trying next port...\n", "INFO:leann.embedding_server_manager:Found compatible server on port 5560\n", "INFO:leann.embedding_server_manager:Using existing compatible server on port 5560\n", "INFO:leann.api: Launching server time: 0.04932403564453125 seconds\n", "INFO:leann.embedding_server_manager:Found compatible server on port 5560\n", "INFO:leann.embedding_server_manager:Using existing compatible server on port 5560\n", "INFO:leann.api: Generated embedding shape: (1, 768)\n", "INFO:leann.api: Embedding time: 0.06902289390563965 seconds\n", "INFO:leann.api: Search time: 0.026793241500854492 seconds\n", "INFO:leann.api: Backend returned: labels=2 results\n", "INFO:leann.api: Processing 2 passage IDs:\n", "INFO:leann.api: 1. passage_id='0' -> SUCCESS: C# is a powerful programming language and it is good at game development...\n", "INFO:leann.api: 2. passage_id='1' -> SUCCESS: Python is a powerful programming language and it is good at machine learning tasks...\n", "INFO:leann.api: Final enriched results: 2 passages\n", "INFO:leann.chat:Generating with HuggingFace model, config: {'max_new_tokens': 128, 'temperature': 0.7, 'top_p': 0.9, 'do_sample': True, 'pad_token_id': 151645, 'eos_token_id': 151645}\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "ZmqDistanceComputer initialized: d=768, metric=0\n" ] }, { "data": { "text/plain": [ "\"\\n\\n\\n\\nBased on the context provided, here's a comparison of the two retrieved programming languages:\\n\\n**C#** is known for being a powerful programming language and is well-suited for game development. It is often used in game development and is popular among developers working on Windows applications.\\n\\n**Python**, on the other hand, is also a powerful language and is well-suited for machine learning tasks. It is widely used for data analysis, scientific computing, and other applications that require handling large datasets or performing complex calculations.\\n\\n**Advantages**:\\n- C#: Strong for game development and cross-platform compatibility.\\n- Python: Strong for\"" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from leann.api import LeannChat\n", "\n", "llm_config = {\n", " \"type\": \"hf\",\n", " \"model\": \"Qwen/Qwen3-0.6B\",\n", "}\n", "\n", "chat = LeannChat(index_path=\"knowledge.leann\", llm_config=llm_config)\n", "response = chat.ask(\n", " \"Compare the two retrieved programming languages and tell me their advantages.\",\n", " top_k=2,\n", " llm_kwargs={\"max_tokens\": 128}\n", ")\n", "response" ] } ], "metadata": { "kernelspec": { "display_name": ".venv", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.12" } }, "nbformat": 4, "nbformat_minor": 2 }