{"id":13736721,"url":"https://github.com/zilliztech/feder","last_synced_at":"2025-05-08T13:31:29.449Z","repository":{"id":37179734,"uuid":"448719118","full_name":"zilliztech/feder","owner":"zilliztech","description":"Visualize hnsw, faiss and other anns index","archived":false,"fork":false,"pushed_at":"2023-03-07T01:32:41.000Z","size":33870,"stargazers_count":360,"open_issues_count":9,"forks_count":31,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-07-13T22:02:13.790Z","etag":null,"topics":["faiss","hnsw","milvus","visualization"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zilliztech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-01-17T01:32:53.000Z","updated_at":"2024-07-12T05:32:35.000Z","dependencies_parsed_at":"2024-02-06T05:51:01.617Z","dependency_job_id":null,"html_url":"https://github.com/zilliztech/feder","commit_stats":{"total_commits":157,"total_committers":5,"mean_commits":31.4,"dds":0.07006369426751591,"last_synced_commit":"9e1c3cae6351545d098a7de75978afef6a927d69"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilliztech%2Ffeder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilliztech%2Ffeder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilliztech%2Ffeder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilliztech%2Ffeder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zilliztech","download_url":"https://codeload.github.com/zilliztech/feder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":213758653,"owners_count":15634354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["faiss","hnsw","milvus","visualization"],"created_at":"2024-08-03T03:01:27.258Z","updated_at":"2024-11-15T05:30:32.592Z","avatar_url":"https://github.com/zilliztech.png","language":"Jupyter Notebook","funding_links":[],"categories":["LLM Tools","Jupyter Notebook"],"sub_categories":[],"readme":"# Feder\n\n## What is feder\n\nFeder is a JavaScript tool designed to aid in the comprehension of embedding vectors. It visualizes index files from Faiss, HNSWlib, and other ANN libraries to provide insight into how these libraries function and the concept of high-dimensional vector embeddings. Currently, Feder is primarily focused on the IVF_FLAT index file type from Faiss and the HNSW index file type from HNSWlib, though additional index types will be added in the future.\n\nFeder is written in **javascript**, and we also provide a python library **federpy**, which is based on federjs.\n\n\u003e **_NOTE:_**\n\n- In IPython environment, it supports users to generate the corresponding visualization directly.\n- In other environments, it supports outputting visualizations as html files, which can be opened by the user through the browser with web service enabled.\n\n\n### Online demos\n- [Understanding vector embeddings with Feder by a reverse image search example](https://observablehq.com/@min-tian/reverse-image-search-feder-faiss-ivf_flat-visualizations)\n- [Javascript example (Observable)](https://observablehq.com/@min-tian/feder)\n- [Jupternotebook example (Colab)](https://colab.research.google.com/drive/12L_oJPR-yFDlORpPondsqGNTPVsSsUwi#scrollTo=N3qqBAYxYcbt)\n\n### How feder works\n- [Feder ivf layout](https://observablehq.com/@min-tian/feder-layout-ivf_flat/2)\n- [Feder hnsw layout ](https://observablehq.com/@min-tian/feder-layout-hnsw/2)\n\n### Wiki\n\n- [Usage](https://github.com/zilliztech/feder/wiki)\n\n### HNSW visualization screenshots\n\n![image](./fig/hnsw_search.png)\n\n### IVF_Flat visualization screenshots\n\n![image](./fig/ivfflat_coarse.png)\n![image](./fig/ivfflat_fine_polar.png)\n![image](./fig/ivfflat_fine_project.png)\n\n## Quick Start\n\n### Installation\n\nUse npm or yarn.\n\n```shell\nyarn install @zilliz/feder\n```\n\n### Material Preparation\n\nMake sure that you have built an index and dumped the index file by Faiss or HNSWlib.\n\n### Init Feder\n\nSpecifying the dom container that you want to show the visualizations.\n\n```js\nimport { Feder } from '@zilliz/feder';\n\nconst feder = new Feder({\n  filePath: 'faiss_file', // file path\n  source: 'faiss', // faiss | hnswlib\n  domSelector: '#container', // attach dom to render\n  viewParams: {}, // optional\n});\n```\n\n### Visualize the index structure.\n\n- HNSW - Feder will show the top-3 levels of the hnsw-tree.\n- IVF_Flat - Feder will show all the clusters.\n\n```js\nfeder.overview();\n```\n\n### Explore the search process.\n\nSet search parameters (optional) and Specify the query vector.\n\n```js\nfeder\n  .setSearchParams({\n    k: 8, // hnsw, ivf_flat\n    ef: 100, // hnsw (ef_search)\n    nprobe: 8, // ivf_flat\n  })\n  .search(target_vector);\n```\n\n## Examples\n\nWe prepare a simple case, which is the visualizations of the `hnsw` and `ivf_flat` with 17,000+ vectors that embedded from [VOC 2012](http://host.robots.ox.ac.uk/pascal/VOC/voc2012/VOCtrainval_11-May-2012.tar)).\n\n```shell\ngit clone git@github.com:zilliztech/feder.git\ncd feder\nyarn install\nyarn dev\n```\n\nThen open http://localhost:12355/\n\nIt will show 4 visualizations:\n- `hnsw` overview\n- `hnsw` search view\n- `ivf_flat` overview\n- `ivf_flat` search view\n\n## Feder for Large Index\n\n`Feder` consists of three components: \n- `FederIndex` - parse the index file. It requires a lot of memory.\n- `FederLayout` - layout calculations. It consumes a lot of computational resources.\n- `FederView` - render and interaction.\n\nIn case of excessive amount of data, we support separating the computation part and running it on a node server.\nWe have two solutions for you:\n- oneServer\n  - federServer (with `FederIndex` and `FederLayout`).\n- twoServer\n  - indexServer (with `FederIndex`)\n  - layoutServer (with `FederLayout`)\n\nReferring to **case/oneServer** and **case/twoServer**.\n\n### Example with One Server\n1. launch the server\n```shell\nyarn test_one_server_backend\n```\n2. launch the front web service\n```shell\nyarn test_one_server_front\n```\n3. open http://localhost:8000\n\n### Example with Two Servers\n1. launch the FederIndex server\n```shell\nyarn test_two_server_feder_index\n```\n2. launch the FederLayout server\n```shell\nyarn test_two_server_feder_layout\n```\n3. launch the front web service\n```shell\nyarn test_two_server_front\n```\n4. open http://localhost:8000\n\n## Pipeline - explore a new dataset with feder\n\n### Step 1. Dataset preparation\n\nPut all images to **test/data/images/**. (example dataset [VOC 2012](http://host.robots.ox.ac.uk/pascal/VOC/voc2012/VOCtrainval_11-May-2012.tar))\n\nYou can also generate random vectors without embedding for index building and skip to **step 3**.\n\n### Step 2. Generate embedding vectors\n\nRecommend to use [towhee](https://github.com/towhee-io/towhee), one line of code to generating embedding vectors!\n\nWe have the [encoded vectors](https://assets.zilliz.com/voc_vectors_e8ec5a5eae.csv) ready for you.\n\n### Step 3. Build an index and dump it.\n\nYou can use [faiss](https://github.com/facebookresearch/faiss) or [hnswlib](https://github.com/nmslib/hnswlib) to build the index.\n\n(\\*Detailed procedures please refer to their tutorials.)\n\nReferring to **test/data/gen_hnswlib_index_\\*.py** or **test/data/gen_faiss_index_\\*.py**\n\nOr we have the [index file](https://assets.zilliz.com/hnswlib_hnsw_voc_17k_1f1dfd63a9.index) ready for you.\n\n### Step 4. Init Feder.\n\n```js\nimport { Feder } from '@zilliz/feder';\nimport * as d3 from 'd3';\n\nconst domSelector = '#container';\nconst filePath = [index_file_path];\nconst source = \"hnswlib\"; // \"hnswlib\" or \"faiss\"\n\nconst mediaCallback = (rowId) =\u003e mediaUrl;\n\nconst feder = new Feder({\n  filePath,\n  source,\n  domSelector,\n  viewParams: {\n    mediaType: 'img',\n    mediaCallback,\n  },\n});\n```\n\nIf use the random_data, **no need** to specify the mediaType.\n\n```js\nimport { Feder } from '@zilliz/feder';\nimport * as d3 from 'd3';\n\nconst domSelector = '#container';\nconst filePath = [index_file_path];\n\nconst feder = new Feder({\n  filePath,\n  source: 'hnswlib',\n  domSelector,\n});\n```\n\n### Step 5. Explore the index!\n\nVisualize the overview\n\n```js\nfeder.overview();\n```\n\nor visualize the search process.\n\n```js\nfeder.search(target_vector[, targetMediaUrl]);\n```\n\nor randomly select an vector as the target to visualize the search process.\n\n```js\nfeder.searchRandTestVec();\n```\n\nMore cases refer to the **test/test.js**\n\n## Blogs\n\n- [Visualize Your Approximate Nearest Neighbor Search with Feder](https://zilliz.com/blog/Visualize-Your-Approximate-Nearest-Neighbor-Search-with-Feder)\n- [Visualize Reverse Image Search with Feder](https://zilliz.com/blog/Visualize-Reverse-Image-Search-with-Feder)\n\n## Roadmap\n\nWe're still in the early stages, we will support more types of anns index, and more unstructured data viewer, stay tuned.\n\n## Acknowledgments\n\n- [faiss](https://github.com/facebookresearch/faiss)\n- [hnswlib](https://github.com/nmslib/hnswlib)\n- [d3](https://github.com/d3/d3)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzilliztech%2Ffeder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzilliztech%2Ffeder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzilliztech%2Ffeder/lists"}