{"id":21475262,"url":"https://github.com/rinx/alvd","last_synced_at":"2025-10-11T20:15:29.859Z","repository":{"id":50871209,"uuid":"308557401","full_name":"rinx/alvd","owner":"rinx","description":"alvd = A Lightweight Vald. A lightweight distributed vector search engine works without K8s.","archived":false,"fork":false,"pushed_at":"2021-06-04T08:02:30.000Z","size":873,"stargazers_count":50,"open_issues_count":1,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-06-20T05:02:47.277Z","etag":null,"topics":["approximate-nearest-neighbor-search","nearest-neighbor-search","ngt","similarity-search","vald","vector-search","vector-search-engine"],"latest_commit_sha":null,"homepage":"https://alvd.netlify.app/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rinx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-30T07:36:03.000Z","updated_at":"2023-09-07T20:10:03.000Z","dependencies_parsed_at":"2022-09-04T00:53:15.665Z","dependency_job_id":null,"html_url":"https://github.com/rinx/alvd","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rinx%2Falvd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rinx%2Falvd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rinx%2Falvd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rinx%2Falvd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rinx","download_url":"https://codeload.github.com/rinx/alvd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226033294,"owners_count":17563125,"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":["approximate-nearest-neighbor-search","nearest-neighbor-search","ngt","similarity-search","vald","vector-search","vector-search-engine"],"created_at":"2024-11-23T10:40:12.364Z","updated_at":"2025-10-11T20:15:24.839Z","avatar_url":"https://github.com/rinx.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"./assets/cover.svg\" width=\"100%\"\u003e\n\u003c/div\u003e\n\nalvd - A Lightweight Vald\n===\n\n[![License: Apache 2.0](https://img.shields.io/github/license/rinx/alvd.svg?style=flat-square)](https://opensource.org/licenses/Apache-2.0)\n[![release](https://img.shields.io/github/release/rinx/alvd.svg?style=flat-square)](https://github.com/rinx/alvd/releases/latest)\n[![ghcr.io](https://img.shields.io/badge/ghcr.io-rinx%2Falvd-brightgreen?logo=docker\u0026style=flat-square)](https://github.com/users/rinx/packages/container/package/alvd)\n[![Docker Pulls](https://img.shields.io/docker/pulls/rinx/alvd.svg?style=flat-square)](https://hub.docker.com/r/rinx/alvd)\n\nA lightweight distributed vector search engine based on [Vald](https://vald.vdaas.org) codebase.\n\n- works without Kubernetes\n- single binary (less than 30MB)\n- easy to run (can be configured by command-line options)\n- consists of Agent and Server\n    - alvd has almost same features that Vald's gateway-lb + discoverer and agent-ngt have.\n\nalvd is highly inspired by [k3s](https://k3s.io) project.\n\nRationale\n---\n\nVald is an awesome highly scalable distributed vector search engine works on Kubernetes.\nIt has great features such as file-based backup, metrics-based ordering of Agents. Also Vald is highly configurable using YAML files.\n\nHowever it requires\n\n- Kubernetes APIs to discover Vald Agents\n- knowledge of operating Kubernetes\n- knowledge of tuning a lot of complicated parameters\n\nit is a little difficult for the users.\n\nIn this project, we eliminated several features of Vald such as (meta, backup manager, index manager, etc...) and just focused on Vald's gateway-lb and agent-ngt.\nBy using [rancher/remotedialer](https://github.com/rancher/remotedialer), Vald's discoverer feature is not needed anymore.\nAlso we eliminated advanced options and adopt command-line options for configuring the application behavior instead of YAML files.\n\nAs stated above, alvd is focused on \"easy to use\", \"Kubernetes-less\" and \"less components\".\n\nHow it works\n---\n\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"./assets/howitworks.svg\"\u003e\n\u003cimg src=\"./assets/howitworks.svg\" width=\"100%\"\u003e\n\u003c/a\u003e\n\u003c/div\u003e\n\nQuick Start\n---\n\n1. Get the latest build from [Release](https://github.com/rinx/alvd/releases) page and unzip it.\n2. Run alvd Server.\n    ```sh\n    $ ./alvd server\n    2020-12-18 19:18:27     [INFO]: start alvd server\n    2020-12-18 19:18:27     [INFO]: metrics server starting on 0.0.0.0:9090\n    2020-12-18 19:18:27     [INFO]: websocket server starting on 0.0.0.0:8000\n    2020-12-18 19:18:27     [INFO]: gateway gRPC API starting on 0.0.0.0:8080\n    INFO[0000] Connecting to proxy                           url=\"ws://0.0.0.0:8000/connect\"\n    2020-12-18 19:18:27     [INFO]: agent gRPC API starting on 0.0.0.0:8081\n    INFO[0000] Handling backend connection request [7q6ai4gbve83spij0s4g]\n    2020-12-18 19:18:27     [INFO]: connected to: 0.0.0.0:8000\n    ```\n    alvd Server's websocket server starts on 0.0.0.0:8000 and alvd Server's gRPC API starts on 0.0.0.0:8080.\n    Also, alvd Agent's gRPC API starts on 0.0.0.0:8081 (alvd Agent process on the Server can be disabled using `--agent=false` option).\n3. Run alvd Agent on a different node (or a different terminal on the same node with `--server 0.0.0.0:8000` and `--grpc-port 8082` option).\n    ```sh\n    $ ./alvd agent --server host-of-server-node:8000\n    $ # ./alvd agent --server 0.0.0.0:8000 --grpc-port 8082 --metrics-port=9091\n    2020-12-18 19:20:15     [INFO]: start alvd agent\n    2020-12-18 19:20:15     [INFO]: metrics server starting on 0.0.0.0:9090\n    INFO[0000] Connecting to proxy                           url=\"ws://host-of-server-node:8000/connect\"\n    2020-12-18 19:20:15     [INFO]: agent gRPC API starting on 0.0.0.0:8081\n    2020-12-18 19:20:15     [INFO]: connected to: host-of-server-node:8000\n    ```\n4. Add more alvd Agents on the other nodes (or the other ports on the same node).\n    ```sh\n    $ ./alvd agent --server host-of-server-node:8000\n    $ # ./alvd agent --server 0.0.0.0:8000 --grpc-port 808{3,4,5} --metrics-port=909{2,3,4}\n    ```\n5. Now we can access the alvd Server's gRPC API (`host-of-server-node:8080`) using Vald v1 clients.\n    If you don't have one, you can use [valdcli](https://github.com/vdaas/vald-client-clj) (this CLI is built for linux-amd64 and macos-amd64).\n    ```sh\n    $ # insert 100 vectors (dimension: 784) with random IDs\n    $ valdcli rand-vecs -d 784 -n 100 --with-ids | valdcli -h host-of-server-node -p 8080 stream-insert\n    $ # search a random vector\n    $ valdcli rand-vec -d 784 | valdcli -h host-of-server-node -p 8080 search\n    ```\n\nDistribution\n---\n\nOn [Release](https://github.com/rinx/alvd/releases) page, alvd binaries for amd64 Linux machines are available.\n\n- alvd-linux-amd64.zip doesn't use AVX instructions.\n- alvd-linux-amd64-avx2.zip uses AVX2 instuctions for distance calculations. It is faster.\n\nDocker images are available on GitHub Package Registries and DockerHub.\nThe images tagged by `noavx` are built for amd64, arm64 and armv7 architectures.\n`avx2` images are only available for amd64 architectures.\n\n- [ghcr.io/rinx/alvd](https://github.com/users/rinx/packages/container/package/alvd)\n- [rinx/alvd](https://hub.docker.com/r/rinx/alvd)\n\nRunning on Docker using Docker Compose\n---\n\nThere's an example [`docker-compose.yml`](https://github.com/rinx/alvd/tree/main/docker-compose.yml) in this repository.\n\nTry to run it with a command:\n\n```sh\n$ docker-compose up\nStarting alvd-agent-2 ... done\nStarting alvd-agent-1 ... done\nStarting alvd-agent-3 ... done\nStarting alvd-server  ... done\nAttaching to alvd-agent-2, alvd-agent-3, alvd-agent-1, alvd-server\nalvd-agent-1    | 2021-04-30 02:33:36   [INFO]: start alvd agent\nalvd-agent-1    | 2021-04-30 02:33:36   [INFO]: metrics server starting on 0.0.0.0:9090\nalvd-agent-2    | 2021-04-30 02:33:35   [INFO]: start alvd agent\nalvd-agent-2    | 2021-04-30 02:33:35   [INFO]: metrics server starting on 0.0.0.0:9090\nalvd-agent-2    | 2021-04-30 02:33:35   [INFO]: agent gRPC API starting on 0.0.0.0:8081\n...\nalvd-server     | 2021-04-30 02:33:36   [INFO]: gateway gRPC API starting on 0.0.0.0:8080\n...\n```\n\nThen 1 Server + 3 Agents will run on your Docker environment.\nWe can access to the alvd Server's gRPC API on 8080 using Vald v1 clients.\n\n```sh\n$ # insert 100 vectors (dimension: 784) with random IDs\n$ valdcli rand-vecs -d 784 -n 100 --with-ids | valdcli -h localhost -p 8080 stream-insert\n$ # search a random vector\n$ valdcli rand-vec -d 784 | valdcli -h localhost -p 8080 search\n```\n\nThe metrics APIs are exported on 9090-9093 ports. We can access them using curl.\n\n```sh\n$ curl http://localhost:9090/metrics\n$ curl http://localhost:9091/metrics\n...\n```\n\nIn the `docker-compose.yml` file, there're definitions of Prometheus and Grafana services. If they are enabled, a metrics dashboard can be displayed on your machine. (http://localhost:3000)\n\n[![Grafana dashboard](https://user-images.githubusercontent.com/1588935/116655813-a7470400-a9c6-11eb-9482-ed6f9369fba2.png)](https://user-images.githubusercontent.com/1588935/116655813-a7470400-a9c6-11eb-9482-ed6f9369fba2.png)\n\nRunning on Kubernetes\n---\n\nThere are example manifests in [k8s](https://github.com/rinx/alvd/tree/main/k8s) directory.\n\n```sh\n$ # create new namespace\n$ kubectl create ns alvd\n$ # change current namespace\n$ kubectl config set-context $(kubectl config current-context) --namespace=alvd\n$ # deploy Servers\n$ kubectl apply -f k8s/server.yaml\n\n$ # after Servers become ready, deploy Agents\n$ kubectl apply -f k8s/agent.yaml\n```\n\nLua based config\n---\n\nInstead of using command-line flags, alvd can be configured by using a Lua based config file.\nThare's an example Lua file at [examples/config/config.lua](examples/config/config.lua).\n\n```sh\n$ ./alvd server --config=examples/config/config.lua\n```\n\n### Interceptor features\n\nalvd has interceptor features (filtering, sorting, translating, etc...) that is extensible by using Lua scripts.  \nTo enable them, run alvd server by passing a path to the Lua scripts.\n\n    $ ./alvd server --config=examples/interceptors/sort.lua\n\nThere're various types of examples of interceptors are available in [examples/interceptors](examples/interceptors) directory and [examples/config/config.lua](examples/config/config.lua).\n\nThis feature is powered by [yuin/gopher-lua](https://github.com/yuin/gopher-lua) and [vadv/gopher-lua-libs](https://github.com/vadv/gopher-lua-libs).\n\nCurrent Status\n---\n\n- Agent uses NGT service package of Vald Agent NGT.\n- uses Vald v1 API on master branch (https://github.com/vdaas/vald/tree/master/apis/proto/v1).\n    - Server has APIs in https://github.com/vdaas/vald/tree/master/apis/proto/v1/vald\n        - Unary APIs and Streaming APIs are supported.\n        - MultiXXX APIs are not supported.\n    - Agent has APIs in https://github.com/vdaas/vald/tree/master/apis/proto/v1/vald and https://github.com/vdaas/vald/tree/master/apis/proto/v1/agent/core.\n        - Unary APIs and Streaming APIs are supported.\n        - MultiXXX APIs are not supported.\n- Currently, high-availability (HA) cluster is partly supported.\n    - Only static IP multiple Servers (+ multiple Agents) can build an alvd HA cluster.\n        - Agents cannot resolve dynamic IPs of Servers.\n    - In the near future, HA cluster will be fully supported.\n\n\nBuild\n---\n\n    $ make cmd/alvd/alvd\n\n\nLicense\n---\n\nSame as Vald, alvd is distributed under Apache 2.0 license. (Partially distributed under Mozilla Public License 2.0)\n\nalvd depends on Vald codebase, the files came from Vald (such as `internal`, `pkg/vald`. They are downloaded when running `make` command.) are excluded from my license and ownership.\n\nThis is not an official project of Vald. This project is an artifact of 20% project of Vald team.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frinx%2Falvd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frinx%2Falvd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frinx%2Falvd/lists"}