Skip to content

Commit 51ac562

Browse files
authored
Merge pull request #779 from AyodeAwe/go-publishing
Go module - Usage docs
1 parent a73c39c commit 51ac562

File tree

10 files changed

+334
-1
lines changed

10 files changed

+334
-1
lines changed

ci/release/update-version.sh

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ sed_runner "/rapidsai\/raft/ s|branch-[0-9][0-9].[0-9][0-9]|branch-${NEXT_SHORT_
8181

8282
sed_runner "s|=[0-9][0-9].[0-9][0-9]|=${NEXT_SHORT_TAG}|g" README.md
8383
sed_runner "s|branch-[0-9][0-9].[0-9][0-9]|branch-${NEXT_SHORT_TAG}|g" README.md
84+
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
8485

8586
# references to license files
8687
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
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# This file is generated by `rapids-dependency-file-generator`.
2+
# To make changes, edit ../../dependencies.yaml and run `rapids-dependency-file-generator`.
3+
channels:
4+
- rapidsai
5+
- rapidsai-nightly
6+
- dask/label/dev
7+
- conda-forge
8+
- nvidia
9+
dependencies:
10+
- c-compiler
11+
- clang-tools==16.0.6
12+
- clang==16.0.6
13+
- cmake>=3.30.4
14+
- cuda-nvtx=11.8
15+
- cuda-profiler-api=11.8.86
16+
- cuda-version=11.8
17+
- cudatoolkit
18+
- cxx-compiler
19+
- dlpack>=0.8,<1.0
20+
- gcc_linux-aarch64=11.*
21+
- go
22+
- libclang==16.0.6
23+
- libcublas-dev=11.11.3.6
24+
- libcublas=11.11.3.6
25+
- libcurand-dev=10.3.0.86
26+
- libcurand=10.3.0.86
27+
- libcusolver-dev=11.4.1.48
28+
- libcusolver=11.4.1.48
29+
- libcusparse-dev=11.7.5.86
30+
- libcusparse=11.7.5.86
31+
- libcuvs==25.4.*,>=0.0.0a0
32+
- libraft==25.4.*,>=0.0.0a0
33+
- nccl>=2.19
34+
- ninja
35+
- nvcc_linux-aarch64=11.8
36+
- sysroot_linux-aarch64==2.28
37+
name: go_cuda-118_arch-aarch64
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# This file is generated by `rapids-dependency-file-generator`.
2+
# To make changes, edit ../../dependencies.yaml and run `rapids-dependency-file-generator`.
3+
channels:
4+
- rapidsai
5+
- rapidsai-nightly
6+
- dask/label/dev
7+
- conda-forge
8+
- nvidia
9+
dependencies:
10+
- c-compiler
11+
- clang-tools==16.0.6
12+
- clang==16.0.6
13+
- cmake>=3.30.4
14+
- cuda-nvtx=11.8
15+
- cuda-profiler-api=11.8.86
16+
- cuda-version=11.8
17+
- cudatoolkit
18+
- cxx-compiler
19+
- dlpack>=0.8,<1.0
20+
- gcc_linux-64=11.*
21+
- go
22+
- libclang==16.0.6
23+
- libcublas-dev=11.11.3.6
24+
- libcublas=11.11.3.6
25+
- libcurand-dev=10.3.0.86
26+
- libcurand=10.3.0.86
27+
- libcusolver-dev=11.4.1.48
28+
- libcusolver=11.4.1.48
29+
- libcusparse-dev=11.7.5.86
30+
- libcusparse=11.7.5.86
31+
- libcuvs==25.4.*,>=0.0.0a0
32+
- libraft==25.4.*,>=0.0.0a0
33+
- nccl>=2.19
34+
- ninja
35+
- nvcc_linux-64=11.8
36+
- sysroot_linux-64==2.28
37+
name: go_cuda-118_arch-x86_64
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# This file is generated by `rapids-dependency-file-generator`.
2+
# To make changes, edit ../../dependencies.yaml and run `rapids-dependency-file-generator`.
3+
channels:
4+
- rapidsai
5+
- rapidsai-nightly
6+
- dask/label/dev
7+
- conda-forge
8+
- nvidia
9+
dependencies:
10+
- c-compiler
11+
- clang-tools==16.0.6
12+
- clang==16.0.6
13+
- cmake>=3.30.4
14+
- cuda-cudart-dev
15+
- cuda-nvcc
16+
- cuda-nvtx-dev
17+
- cuda-profiler-api
18+
- cuda-version=12.8
19+
- cxx-compiler
20+
- dlpack>=0.8,<1.0
21+
- gcc_linux-aarch64=13.*
22+
- go
23+
- libclang==16.0.6
24+
- libcublas-dev
25+
- libcurand-dev
26+
- libcusolver-dev
27+
- libcusparse-dev
28+
- libcuvs==25.4.*,>=0.0.0a0
29+
- libraft==25.4.*,>=0.0.0a0
30+
- nccl>=2.19
31+
- ninja
32+
- sysroot_linux-aarch64==2.28
33+
name: go_cuda-128_arch-aarch64
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# This file is generated by `rapids-dependency-file-generator`.
2+
# To make changes, edit ../../dependencies.yaml and run `rapids-dependency-file-generator`.
3+
channels:
4+
- rapidsai
5+
- rapidsai-nightly
6+
- dask/label/dev
7+
- conda-forge
8+
- nvidia
9+
dependencies:
10+
- c-compiler
11+
- clang-tools==16.0.6
12+
- clang==16.0.6
13+
- cmake>=3.30.4
14+
- cuda-cudart-dev
15+
- cuda-nvcc
16+
- cuda-nvtx-dev
17+
- cuda-profiler-api
18+
- cuda-version=12.8
19+
- cxx-compiler
20+
- dlpack>=0.8,<1.0
21+
- gcc_linux-64=13.*
22+
- go
23+
- libclang==16.0.6
24+
- libcublas-dev
25+
- libcurand-dev
26+
- libcusolver-dev
27+
- libcusparse-dev
28+
- libcuvs==25.4.*,>=0.0.0a0
29+
- libraft==25.4.*,>=0.0.0a0
30+
- nccl>=2.19
31+
- ninja
32+
- sysroot_linux-64==2.28
33+
name: go_cuda-128_arch-x86_64

dependencies.yaml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,10 @@ files:
9292
- depends_on_libcuvs
9393
- depends_on_libraft
9494
go:
95-
output: none
95+
output: conda
96+
matrix:
97+
cuda: ["11.8", "12.8"]
98+
arch: [x86_64, aarch64]
9699
includes:
97100
- clang
98101
- cuda

examples/go/README.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# cuVS Go Bindings
2+
3+
This package provides Go bindings for the cuVS (CUDA Vector Search) library.
4+
5+
## Prerequisites
6+
7+
The required dependencies can be installed with a simple command (which creates your build environment):
8+
9+
```bash
10+
conda env create --name go -f conda/environments/go_cuda-128_arch-x86_64.yaml
11+
conda activate go
12+
```
13+
You may prefer to use `mamba`, as it provides significant speedup over `conda`.
14+
15+
## Installation
16+
17+
1. Set up the required environment variables:
18+
```bash
19+
export CGO_CFLAGS="-I${CONDA_PREFIX}/include"
20+
export CGO_LDFLAGS="-L${CONDA_PREFIX}/lib -lcudart -lcuvs -lcuvs_c"
21+
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"
22+
export CC=clang
23+
```
24+
25+
2. Install the Go module:
26+
```bash
27+
go get github.com/rapidsai/cuvs/[email protected] # 25.02.00 being your desired version, selected from https://github.com/rapidsai/cuvs/tags
28+
```
29+
Then you can build your project with the usual `go build`.
30+
31+
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.
32+
33+
## Example Usage
34+
35+
```go
36+
package main
37+
38+
import (
39+
"github.com/rapidsai/cuvs/go"
40+
"github.com/rapidsai/cuvs/go/cagra"
41+
)
42+
43+
func main() {
44+
// Example code showing how to use the library
45+
}
46+
```
47+
See [main.go](./main.go) for an example implementation.

examples/go/go.mod

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
module cuvs-example
2+
3+
go 1.22.4
4+
5+
toolchain go1.23.6
6+
7+
require github.com/rapidsai/cuvs/go v0.0.0-20250313193519-2f9df39e52cc

examples/go/go.sum

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
github.com/rapidsai/cuvs/go v0.0.0-20250313193519-2f9df39e52cc h1:KaikmdTcld8icYGg5/5K1U69FTRpXlnYJZPBPFPrV5g=
2+
github.com/rapidsai/cuvs/go v0.0.0-20250313193519-2f9df39e52cc/go.mod h1:qQPopaJ6Z5DXM+HqtP8TzatknrfiCE7vBf/p1+lVFr8=

examples/go/main.go

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
package main
2+
3+
import (
4+
"fmt"
5+
"log"
6+
"math/rand"
7+
"time"
8+
9+
cuvs "github.com/rapidsai/cuvs/go"
10+
"github.com/rapidsai/cuvs/go/cagra"
11+
)
12+
13+
func main() {
14+
// Initialize resources
15+
resources, err := cuvs.NewResource(nil)
16+
if err != nil {
17+
log.Fatalf("Failed to create resources: %v", err)
18+
}
19+
defer resources.Close()
20+
21+
// Dataset
22+
const (
23+
nDatapoints = 65536
24+
nFeatures = 512
25+
nQueries = 4
26+
k = 10
27+
)
28+
29+
// Create random dataset
30+
rand.Seed(time.Now().UnixNano())
31+
dataset := make([][]float32, nDatapoints)
32+
for i := range dataset {
33+
dataset[i] = make([]float32, nFeatures)
34+
for j := range dataset[i] {
35+
dataset[i][j] = rand.Float32()
36+
}
37+
}
38+
39+
// Create tensor from dataset
40+
datasetTensor, err := cuvs.NewTensor(dataset)
41+
if err != nil {
42+
log.Fatalf("Failed to create dataset tensor: %v", err)
43+
}
44+
defer datasetTensor.Close()
45+
46+
// Move dataset to GPU
47+
if _, err := datasetTensor.ToDevice(&resources); err != nil {
48+
log.Fatalf("Failed to move dataset to GPU: %v", err)
49+
}
50+
51+
// Create and configure CAGRA index
52+
indexParams, err := cagra.CreateIndexParams()
53+
if err != nil {
54+
log.Fatalf("Failed to create index params: %v", err)
55+
}
56+
defer indexParams.Close()
57+
58+
index, err := cagra.CreateIndex()
59+
if err != nil {
60+
log.Fatalf("Failed to create index: %v", err)
61+
}
62+
defer index.Close()
63+
64+
// Build the index
65+
fmt.Printf("Building index for %d vectors with %d dimensions...\n", nDatapoints, nFeatures)
66+
if err := cagra.BuildIndex(resources, indexParams, &datasetTensor, index); err != nil {
67+
log.Fatalf("Failed to build index: %v", err)
68+
}
69+
70+
// Create query tensor (using first few vectors as queries)
71+
queries, err := cuvs.NewTensor(dataset[:nQueries])
72+
if err != nil {
73+
log.Fatalf("Failed to create queries tensor: %v", err)
74+
}
75+
defer queries.Close()
76+
77+
// Move queries to GPU
78+
if _, err := queries.ToDevice(&resources); err != nil {
79+
log.Fatalf("Failed to move queries to GPU: %v", err)
80+
}
81+
82+
// Create tensors for results
83+
neighbors, err := cuvs.NewTensorOnDevice[uint32](&resources, []int64{int64(nQueries), int64(k)})
84+
if err != nil {
85+
log.Fatalf("Failed to create neighbors tensor: %v", err)
86+
}
87+
defer neighbors.Close()
88+
89+
distances, err := cuvs.NewTensorOnDevice[float32](&resources, []int64{int64(nQueries), int64(k)})
90+
if err != nil {
91+
log.Fatalf("Failed to create distances tensor: %v", err)
92+
}
93+
defer distances.Close()
94+
95+
// Create search parameters
96+
searchParams, err := cagra.CreateSearchParams()
97+
if err != nil {
98+
log.Fatalf("Failed to create search params: %v", err)
99+
}
100+
defer searchParams.Close()
101+
102+
// Perform the search
103+
fmt.Printf("Searching for %d nearest neighbors for %d queries...\n", k, nQueries)
104+
if err := cagra.SearchIndex(resources, searchParams, index, &queries, &neighbors, &distances, nil); err != nil {
105+
log.Fatalf("Failed to search index: %v", err)
106+
}
107+
108+
// Get results
109+
if _, err := neighbors.ToHost(&resources); err != nil {
110+
log.Fatalf("Failed to move neighbors to host: %v", err)
111+
}
112+
if _, err := distances.ToHost(&resources); err != nil {
113+
log.Fatalf("Failed to move distances to host: %v", err)
114+
}
115+
resources.Sync()
116+
117+
neighborsResult, err := neighbors.Slice()
118+
if err != nil {
119+
log.Fatalf("Failed to get neighbors result: %v", err)
120+
}
121+
distancesResult, err := distances.Slice()
122+
if err != nil {
123+
log.Fatalf("Failed to get distances result: %v", err)
124+
}
125+
126+
// Print results
127+
fmt.Println("\nSearch Results:")
128+
for i := 0; i < nQueries; i++ {
129+
fmt.Printf("\nQuery %d:\n", i)
130+
fmt.Printf("Neighbors: %v\n", neighborsResult[i])
131+
fmt.Printf("Distances: %v\n", distancesResult[i])
132+
}
133+
}

0 commit comments

Comments
 (0)