8000 Go module - Usage docs by AyodeAwe · Pull Request #779 · rapidsai/cuvs · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Go module - Usage docs #779

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 3, 2025
Merged

Go module - Usage docs #779

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e189182
go publishing POC
AyodeAwe Mar 24, 2025
31da236
update version in examples/go/readme
AyodeAwe Mar 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions ci/release/update-version.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,7 @@ sed_runner "/rapidsai\/raft/ s|branch-[0-9][0-9].[0-9][0-9]|branch-${NEXT_SHORT_

sed_runner "s|=[0-9][0-9].[0-9][0-9]|=${NEXT_SHORT_TAG}|g" README.md
sed_runner "s|branch-[0-9][0-9].[0-9][0-9]|branch-${NEXT_SHORT_TAG}|g" README.md
sed_runner "s|@v[0-9][0-9].[0-9][0-9].[0-9][0-9]|@v${NEXT_FULL_TAG}|g" examples/go/README.md

# references to license files
sed_runner "s|branch-[0-9][0-9].[0-9][0-9]|branch-${NEXT_SHORT_TAG}|g" python/cuvs_bench/cuvs_bench/plot/__main__.py
Expand Down
37 changes: 37 additions & 0 deletions conda/environments/go_cuda-118_arch-aarch64.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# This file is generated by `rapids-dependency-file-generator`.
# To make changes, edit ../../dependencies.yaml and run `rapids-dependency-file-generator`.
channels:
- rapidsai
- rapidsai-nightly
- dask/label/dev
- conda-forge
- nvidia
dependencies:
- c-compiler
- clang-tools==16.0.6
- clang==16.0.6
- cmake>=3.30.4
- cuda-nvtx=11.8
- cuda-profiler-api=11.8.86
- cuda-version=11.8
- cudatoolkit
- cxx-compiler
- dlpack>=0.8,<1.0
- gcc_linux-aarch64=11.*
- go
- libclang==16.0.6
- libcublas-dev=11.11.3.6
- libcublas=11.11.3.6
- libcurand-dev=10.3.0.86
- libcurand=10.3.0.86
- libcusolver-dev=11.4.1.48
- libcusolver=11.4.1.48
- libcusparse-dev=11.7.5.86
- libcusparse=11.7.5.86
- libcuvs==25.4.*,>=0.0.0a0
- libraft==25.4.*,>=0.0.0a0
- nccl>=2.19
- ninja
- nvcc_linux-aarch64=11.8
- sysroot_linux-aarch64==2.28
name: go_cuda-118_arch-aarch64
37 changes: 37 additions & 0 deletions conda/environments/go_cuda-118_arch-x86_64.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# This file is generated by `rapids-dependency-file-generator`.
# To make changes, edit ../../dependencies.yaml and run `rapids-dependency-file-generator`.
channels:
- rapidsai
- rapidsai-nightly
- dask/label/dev
- conda-forge
- nvidia
dependencies:
- c-compiler
- clang-tools==16.0.6
- clang==16.0.6
- cmake>=3.30.4
- cuda-nvtx=11.8
- cuda-profiler-api=11.8.86
- cuda-version=11.8
- cudatoolkit
- cxx-compiler
- dlpack>=0.8,<1.0
- gcc_linux-64=11.*
- go
- libclang==16.0.6
- libcublas-dev=11.11.3.6
- libcublas=11.11.3.6
- libcurand-dev=10.3.0.86
- libcurand=10.3.0.86
- libcusolver-dev=11.4.1.48
- libcusolver=11.4.1.48
- libcusparse-dev=11.7.5.86
- libcusparse=11.7.5.86
- libcuvs==25.4.*,>=0.0.0a0
- libraft==25.4.*,>=0.0.0a0
- nccl>=2.19
- ninja
- nvcc_linux-64=11.8
- sysroot_linux-64==2.28
name: go_cuda-118_arch-x86_64
33 changes: 33 additions & 0 deletions conda/environments/go_cuda-128_arch-aarch64.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# This file is generated by `rapids-dependency-file-generator`.
# To make changes, edit ../../dependencies.yaml and run `rapids-dependency-file-generator`.
channels:
- rapidsai
- rapidsai-nightly
- dask/label/dev
- conda-forge
- nvidia
dependencies:
- c-compiler
- clang-tools==16.0.6
- clang==16.0.6
- cmake>=3.30.4
- cuda-cudart-dev
- cuda-nvcc
- cuda-nvtx-dev
- cuda-profiler-api
- cuda-version=12.8
- cxx-compiler
- dlpack>=0.8,<1.0
- gcc_linux-aarch64=13.*
- go
- libclang==16.0.6
- libcublas-dev
- libcurand-dev
- libcusolver-dev
- libcusparse-dev
- libcuvs==25.4.*,>=0.0.0a0
- libraft==25.4.*,>=0.0.0a0
- nccl>=2.19
- ninja
- sysroot_linux-aarch64==2.28
name: go_cuda-128_arch-aarch64
33 changes: 33 additions & 0 deletions conda/environments/go_cuda-128_arch-x86_64.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# This file is generated by `rapids-dependency-file-generator`.
# To make changes, edit ../../dependencies.yaml and run `rapids-dependency-file-generator`.
channels:
- rapidsai
- rapidsai-nightly
- dask/label/dev
- conda-forge
- nvidia
dependencies:
- c-compiler
- clang-tools==16.0.6
- clang==16.0.6
- cmake>=3.30.4
- cuda-cudart-dev
- cuda-nvcc
- cuda-nvtx-dev
- cuda-profiler-api
- cuda-version=12.8
- cxx-compiler
- dlpack>=0.8,<1.0
- gcc_linux-64=13.*
- go
- libclang==16.0.6
- libcublas-dev
- libcurand-dev
- libcusolver-dev
- libcusparse-dev
- libcuvs==25.4.*,>=0.0.0a0
- libraft==25.4.*,>=0.0.0a0
- nccl>=2.19
- ninja
- sysroot_linux-64==2.28
name: go_cuda-128_arch-x86_64
5 changes: 4 additions & 1 deletion dependencies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,10 @@ files:
- depends_on_libcuvs
- depends_on_libraft
go:
output: none
output: conda
matrix:
cuda: ["11.8", "12.8"]
arch: [x86_64, aarch64]
includes:
- clang
- cuda
Expand Down
47 changes: 47 additions & 0 deletions examples/go/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# cuVS Go Bindings

This package provides Go bindings for the cuVS (CUDA Vector Search) library.

## Prerequisites

The required dependencies can be installed with a simple command (which creates your build environment):

```bash
conda env create --name go -f conda/environments/go_cuda-128_arch-x86_64.yaml
conda activate go
```
You may prefer to use `mamba`, as it provides significant speedup over `conda`.

## Installation

1. Set up the required environment variables:
```bash
export CGO_CFLAGS="-I${CONDA_PREFIX}/include"
export CGO_LDFLAGS="-L${CONDA_PREFIX}/lib -lcudart -lcuvs -lcuvs_c"
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"
export CC=clang
```

2. Install the Go module:
```bash
go get github.com/rapidsai/cuvs/go@v25.02.00 # 25.02.00 being your desired version, selected from https://github.com/rapidsai/cuvs/tags
```
Then you can build your project with the usual `go build`.

Note: The installation will fail if the C libraries are not properly installed and the environment variables are not set correctly, as this module requires CGO compilation.

## Example Usage

```go
package main

import (
"github.com/rapidsai/cuvs/go"
"github.com/rapidsai/cuvs/go/cagra"
)

func main() {
// Example code showing how to use the library
}
```
See [main.go](./main.go) for an example implementation.
7 changes: 7 additions & 0 deletions examples/go/go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
module cuvs-example

go 1.22.4

toolchain go1.23.6

require github.com/rapidsai/cuvs/go v0.0.0-20250313193519-2f9df39e52cc
2 changes: 2 additions & 0 deletions examples/go/go.sum
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
github.com/rapidsai/cuvs/go v0.0.0-20250313193519-2f9df39e52cc h1:KaikmdTcld8icYGg5/5K1U69FTRpXlnYJZPBPFPrV5g=
github.com/rapidsai/cuvs/go v0.0.0-20250313193519-2f9df39e52cc/go.mod h1:qQPopaJ6Z5DXM+HqtP8TzatknrfiCE7vBf/p1+lVFr8=
133 changes: 133 additions & 0 deletions examples/go/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
package main

import (
"fmt"
"log"
"math/rand"
"time"

cuvs "github.com/rapidsai/cuvs/go"
"github.com/rapidsai/cuvs/go/cagra"
)

func main() {
// Initialize resources
resources, err := cuvs.NewResource(nil)
if err != nil {
log.Fatalf("Failed to create resources: %v", err)
}
defer resources.Close()

// Dataset
const (
nDatapoints = 65536
nFeatures = 512
nQueries = 4
k = 10
)

// Create random dataset
rand.Seed(time.Now().UnixNano())
dataset := make([][]float32, nDatapoints)
for i := range dataset {
dataset[i] = make([]float32, nFeatures)
for j := range dataset[i] {
dataset[i][j] = rand.Float32()
}
}

// Create tensor from dataset
datasetTensor, err := cuvs.NewTensor(dataset)
if err != nil {
log.Fatalf("Failed to create dataset tensor: %v", err)
}
defer datasetTensor.Close()

// Move dataset to GPU
if _, err := datasetTensor.ToDevice(&resources); err != nil {
log.Fatalf("Failed to move dataset to GPU: %v", err)
}

// Create and configure CAGRA index
indexParams, err := cagra.CreateIndexParams()
if err != nil {
log.Fatalf("Failed to create index params: %v", err)
}
defer indexParams.Close()

index, err := cagra.CreateIndex()
if err != nil {
log.Fatalf("Failed to create index: %v", err)
}
defer index.Close()

// Build the index
fmt.Printf("Building index for %d vectors with %d dimensions...\n", nDatapoints, nFeatures)
if err := cagra.BuildIndex(resources, indexParams, &datasetTensor, index); err != nil {
log.Fatalf("Failed to build index: %v", err)
}

// Create query tensor (using first few vectors as queries)
queries, err := cuvs.NewTensor(dataset[:nQueries])
if err != nil {
log.Fatalf("Failed to create queries tensor: %v", err)
}
defer queries.Close()

// Move queries to GPU
if _, err := queries.ToDevice(&resources); err != nil {
log.Fatalf("Failed to move queries to GPU: %v", err)
}

// Create tensors for results
neighbors, err := cuvs.NewTensorOnDevice[uint32](&resources, []int64{int64(nQueries), int64(k)})
if err != nil {
log.Fatalf("Failed to create neighbors tensor: %v", err)
}
defer neighbors.Close()

distances, err := cuvs.NewTensorOnDevice[float32](&resources, []int64{int64(nQueries), int64(k)})
if err != nil {
log.Fatalf("Failed to create distances tensor: %v", err)
}
defer distances.Close()

// Create search parameters
searchParams, err := cagra.CreateSearchParams()
if err != nil {
log.Fatalf("Failed to create search params: %v", err)
}
defer searchParams.Close()

// Perform the search
fmt.Printf("Searching for %d nearest neighbors for %d queries...\n", k, nQueries)
if err := cagra.SearchIndex(resources, searchParams, index, &queries, &neighbors, &distances, nil); err != nil {
log.Fatalf("Failed to search index: %v", err)
}

// Get results
if _, err := neighbors.ToHost(&resources); err != nil {
log.Fatalf("Failed to move neighbors to host: %v", err)
}
if _, err := distances.ToHost(&resources); err != nil {
log.Fatalf("Failed to move distances to host: %v", err)
}
resources.Sync()

neighborsResult, err := neighbors.Slice()
if err != nil {
log.Fatalf("Failed to get neighbors result: %v", err)
}
distancesResult, err := distances.Slice()
if err != nil {
log.Fatalf("Failed to get distances result: %v", err)
}

// Print results
fmt.Println("\nSearch Results:")
for i := 0; i < nQueries; i++ {
fmt.Printf("\nQuery %d:\n", i)
fmt.Printf("Neighbors: %v\n", neighborsResult[i])
fmt.Printf("Distances: %v\n", distancesResult[i])
}
}
Loading
0