{"id":21872365,"url":"https://github.com/kanchishimono/python-faiss-grpc-server","last_synced_at":"2025-08-01T10:05:49.005Z","repository":{"id":55498892,"uuid":"294335596","full_name":"KanchiShimono/python-faiss-grpc-server","owner":"KanchiShimono","description":"Simple gRPC server for vector searching implemented by Python and Faiss","archived":false,"fork":false,"pushed_at":"2020-12-26T10:14:34.000Z","size":25,"stargazers_count":7,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-15T00:05:28.024Z","etag":null,"topics":["ann","anns","approximate-nearest-neighbor-search","faiss","grpc","grpc-server","image-search","nearest-neighbor-search","python3","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Python","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/KanchiShimono.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}},"created_at":"2020-09-10T07:27:10.000Z","updated_at":"2024-11-20T14:03:24.000Z","dependencies_parsed_at":"2022-08-15T01:50:33.597Z","dependency_job_id":null,"html_url":"https://github.com/KanchiShimono/python-faiss-grpc-server","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KanchiShimono%2Fpython-faiss-grpc-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KanchiShimono%2Fpython-faiss-grpc-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KanchiShimono%2Fpython-faiss-grpc-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KanchiShimono%2Fpython-faiss-grpc-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KanchiShimono","download_url":"https://codeload.github.com/KanchiShimono/python-faiss-grpc-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248981261,"owners_count":21193147,"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":["ann","anns","approximate-nearest-neighbor-search","faiss","grpc","grpc-server","image-search","nearest-neighbor-search","python3","vector-search"],"created_at":"2024-11-28T06:20:17.514Z","updated_at":"2025-04-15T00:06:00.950Z","avatar_url":"https://github.com/KanchiShimono.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# python-faiss-grpc-server\n\n[![GitHub Actions Status](https://github.com/KanchiShimono/python-faiss-grpc-server/workflows/Build/badge.svg)](https://github.com/KanchiShimono/python-faiss-grpc-server/actions?query=workflow%3ABuild)\n\nPython gRPC server for apploximate nearest neighbor by [Faiss](https://github.com/facebookresearch/faiss).\n\n## Installation\n\nYou can install as package by pip install on repository root.\n\n```sh\npip install .\n```\n\n## Usage\n\nYou can start gRPC server by running following command.\n\n```sh\npython python/faiss_grpc/main.py\n```\n\n### Environment variable\n\nPython Faiss gRPC server has some environment variables starts with prefix `FAISS_GRPC_`.\n\n| Variable                   | Default | Description                                                            | Required |\n| :------------------------- | :------ | :--------------------------------------------------------------------- | :------: |\n| FAISS_GRPC_INDEX_PATH      | -       | Path to Faiss index                                                    |    o     |\n| FAISS_GRPC_NORMALIZE_QUERY | False   | Normalize query for search (This is useful to cosine distance metrics) |    x     |\n| FAISS_GRPC_NPROBE          | None    | Faiss nprobe parameter                                                 |    x     |\n| FAISS_GRPC_HOST            | [::]    | gRPC server host                                                       |    x     |\n| FAISS_GRPC_PORT            | 50051   | gRPC server listening port                                             |    x     |\n| FAISS_GRPC_MAX_WORKERS     | 10      | Maximum number of gRPC server workers                                  |    x     |\n\n#### Support .env file\n\nPython Faiss gRPC server supports `.env` file, above environment variables can specified like\n\n```sh\n# .env\nFAISS_GRPC_INDEX_PATH=/path/to/index\nFAISS_GRPC_NORMALIZE_QUERY=True\nFAISS_GRPC_NPROBE=10\n\nFAISS_GRPC_HOST=[::]\nFAISS_GRPC_PORT=50051\nFAISS_GRPC_MAX_WORKERS=2\n```\n\n## Examples\n\nClient side code is under the `examples/client.py`.\nYou can run following command or directly running on interpreter.\n\n```sh\ncd examples\n\n# show usage of client example\npython client.py -h\n\n# show heatbeat message\npython client.py heatbeat\n\n# search by query, get numer of neighbors given value (query is auto generated in command as identity vector)\npython client.py search 10\n\n# search by specified id, get numer of neighbors given value\npython client.py search-by-id 0 10\n```\n\n## Development\n\n### Generate python code\n\nFollowing command will generate two python grpc code `faiss_pb2.py` and `faiss_pb2_grpc.py` under the `python/faiss_grpc/proto`.\nIf you update grpc definition `proto/faiss.proto`, you should regenerate at first.\n\n```sh\nmake codegen\n```\n\nThen you have to fix import path in `faiss_pb2_grpc.py`.\n\n```py\n# Before\nimport faiss_pb2 as faiss__pb2\n# After\nimport faiss_grpc.proto.faiss_pb2 as faiss__pb2\n```\n\n## Cautionary points\n\n- Avoid to use SearchById on the index built by add_with_ids (can use from IndexIDMap, IndexIVF etc.). These index does not keep id complicatedly so reconstruct_n method may do unexpected behavior.\n- Support only CPU index.\n\n## Future work\n\n- [ ] Prepare docker image\n- [ ] Auto download index from remote location if `FAISS_GRPC_INDEX_PATH` was specified remote path\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanchishimono%2Fpython-faiss-grpc-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkanchishimono%2Fpython-faiss-grpc-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanchishimono%2Fpython-faiss-grpc-server/lists"}