docs: add redis examples, lower implOptions

components/indexer/redis/examples/customized_indexer/create_index.go

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	keyPrefix = "eino_doc_customized:"  // keyPrefix should be the prefix of keys you write to redis and want to retrieve.
+	indexName = "test_index_customized" // indexName should be used in redis retriever.
+
+	customContentFieldName       = "my_content_field"
+	customContentVectorFieldName = "my_vector_content_field"
+	customExtraFieldName         = "extra_field_number"
+)
+
+func createIndex() {
+	ctx := context.Background()
+	client := redis.NewClient(&redis.Options{
+		Addr: "localhost:6379",
+	})
+
+	// below use FT.CREATE to create an index.
+	// see: https://redis.io/docs/latest/commands/ft.create/
+
+	// schemas should match DocumentToHashes configured in IndexerConfig.
+	schemas := []*redis.FieldSchema{
+		{
+			FieldName: customContentFieldName,
+			FieldType: redis.SearchFieldTypeText,
+		},
+		{
+			FieldName: customContentVectorFieldName,
+			FieldType: redis.SearchFieldTypeVector,
+			VectorArgs: &redis.FTVectorArgs{
+				// FLAT index: https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/vectors/#flat-index
+				// Choose the FLAT index when you have small datasets (< 1M vectors) or when perfect search accuracy is more important than search latency.
+				FlatOptions: &redis.FTFlatOptions{
+					Type:           "FLOAT32", // BFLOAT16 / FLOAT16 / FLOAT32 / FLOAT64. BFLOAT16 and FLOAT16 require v2.10 or later.
+					Dim:            1024,      // keeps same with dimensions of Embedding
+					DistanceMetric: "COSINE",  // L2 / IP / COSINE
+				},
+				// HNSW index: https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/vectors/#hnsw-index
+				// HNSW, or hierarchical navigable small world, is an approximate nearest neighbors algorithm that uses a multi-layered graph to make vector search more scalable.
+				HNSWOptions: nil,
+			},
+		},
+		{
+			FieldName: customExtraFieldName,
+			FieldType: redis.SearchFieldTypeNumeric,
+		},
+	}
+
+	options := &redis.FTCreateOptions{
+		OnHash: true,
+		Prefix: []any{keyPrefix},
+	}
+
+	result, err := client.FTCreate(ctx, indexName, options, schemas...).Result()
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(result) // OK
+}

components/indexer/redis/examples/customized_indexer/customized_indexer.go

@@ -0,0 +1,119 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+
+	ri "github.com/cloudwego/eino-ext/components/indexer/redis"
+	"github.com/cloudwego/eino/components/embedding"
+	"github.com/cloudwego/eino/schema"
+	"github.com/redis/go-redis/v9"
+)
+
+// This example is related to example in https://github.com/cloudwego/eino-ext/tree/main/components/retriever/redis/examples/customized_retriever
+
+func main() {
+	ctx := context.Background()
+	client := redis.NewClient(&redis.Options{
+		Addr: "localhost:6379",
+	})
+
+	b, err := os.ReadFile("./examples/embeddings.json")
+	if err != nil {
+		panic(err)
+	}
+
+	var dense [][]float64
+	if err = json.Unmarshal(b, &dense); err != nil {
+		panic(err)
+	}
+
+	indexer, err := ri.NewIndexer(ctx, &ri.IndexerConfig{
+		Client:    client,
+		KeyPrefix: keyPrefix,
+		DocumentToHashes: func(ctx context.Context, doc *schema.Document) (*ri.Hashes, error) {
+			f2v := map[string]ri.FieldValue{
+				// write doc.Content to field "my_content_field"
+				// write vector of doc.Content to field "my_vector_content_field"
+				customContentFieldName: {
+					Value:     doc.Content,
+					EmbedKey:  customContentVectorFieldName,
+					Stringify: nil,
+				},
+				// write doc.Metadata["ext"] to field "extra_field_number"
+				customExtraFieldName: {
+					Value: doc.MetaData["ext"],
+				},
+			}
+
+			return &ri.Hashes{
+				Key:         doc.ID + "_suffix",
+				Field2Value: f2v,
+			}, nil
+		},
+		BatchSize: 5,
+		Embedding: &mockEmbedding{dense}, // replace with real embedding
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	contents := `1. Eiffel Tower: Located in Paris, France, it is one of the most famous landmarks in the world, designed by Gustave Eiffel and built in 1889.
+2. The Great Wall: Located in China, it is one of the Seven Wonders of the World, built from the Qin Dynasty to the Ming Dynasty, with a total length of over 20000 kilometers.
+3. Grand Canyon National Park: Located in Arizona, USA, it is famous for its deep canyons and magnificent scenery, which are cut by the Colorado River.
+4. The Colosseum: Located in Rome, Italy, built between 70-80 AD, it was the largest circular arena in the ancient Roman Empire.
+5. Taj Mahal: Located in Agra, India, it was completed by Mughal Emperor Shah Jahan in 1653 to commemorate his wife and is one of the New Seven Wonders of the World.
+6. Sydney Opera House: Located in Sydney Harbour, Australia, it is one of the most iconic buildings of the 20th century, renowned for its unique sailboat design.
+7. Louvre Museum: Located in Paris, France, it is one of the largest museums in the world with a rich collection, including Leonardo da Vinci's Mona Lisa and Greece's Venus de Milo.
+8. Niagara Falls: located at the border of the United States and Canada, consisting of three main waterfalls, its spectacular scenery attracts millions of tourists every year.
+9. St. Sophia Cathedral: located in Istanbul, Türkiye, originally built in 537 A.D., it used to be an Orthodox cathedral and mosque, and now it is a museum.
+10. Machu Picchu: an ancient Inca site located on the plateau of the Andes Mountains in Peru, one of the New Seven Wonders of the World, with an altitude of over 2400 meters.`
+
+	var docs []*schema.Document
+	for idx, str := range strings.Split(contents, "\n") {
+		docs = append(docs, &schema.Document{
+			ID:      strconv.FormatInt(int64(idx+1), 10),
+			Content: str,
+			MetaData: map[string]any{
+				"ext": 10001 + idx, // additional field to write
+			},
+		})
+	}
+
+	ids, err := indexer.Store(ctx, docs)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(ids) // [1 2 3 4 5 6 7 8 9 10]
+	// redis hashes keys are eino_doc_customized:1, eino_doc_customized:2 ...
+}
+
+// mockEmbedding returns embeddings with 1024 dimensions
+type mockEmbedding struct {
+	dense [][]float64
+}
+
+func (m mockEmbedding) EmbedStrings(ctx context.Context, texts []string, opts ...embedding.Option) ([][]float64, error) {
+	return m.dense, nil
+}

components/indexer/redis/examples/default_indexer/create_index.go

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/redis/go-redis/v9"
+)
+
+func createIndex() {
+	ctx := context.Background()
+	client := redis.NewClient(&redis.Options{
+		Addr: "localhost:6379",
+	})
+
+	// below use FT.CREATE to create an index.
+	// see: https://redis.io/docs/latest/commands/ft.create/
+
+	keyPrefix := "eino_doc:"  // keyPrefix should be the prefix of keys you write to redis and want to retrieve.
+	indexName := "test_index" // indexName should be used in redis retriever.
+
+	// schemas should match DocumentToHashes configured in IndexerConfig.
+	schemas := []*redis.FieldSchema{
+		{
+			FieldName: "content",
+			FieldType: redis.SearchFieldTypeText,
+			Weight:    1,
+		},
+		{
+			FieldName: "vector_content",
+			FieldType: redis.SearchFieldTypeVector,
+			VectorArgs: &redis.FTVectorArgs{
+				// FLAT index: https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/vectors/#flat-index
+				// Choose the FLAT index when you have small datasets (< 1M vectors) or when perfect search accuracy is more important than search latency.
+				FlatOptions: &redis.FTFlatOptions{
+					Type:           "FLOAT32", // BFLOAT16 / FLOAT16 / FLOAT32 / FLOAT64. BFLOAT16 and FLOAT16 require v2.10 or later.
+					Dim:            1024,      // keeps same with dimensions of Embedding
+					DistanceMetric: "COSINE",  // L2 / IP / COSINE
+				},
+				// HNSW index: https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/vectors/#hnsw-index
+				// HNSW, or hierarchical navigable small world, is an approximate nearest neighbors algorithm that uses a multi-layered graph to make vector search more scalable.
+				HNSWOptions: nil,
+			},
+		},
+		{
+			FieldName: "extra_field_number",
+			FieldType: redis.SearchFieldTypeNumeric,
+		},
+	}
+
+	options := &redis.FTCreateOptions{
+		OnHash: true,
+		Prefix: []any{keyPrefix},
+	}
+
+	result, err := client.FTCreate(ctx, indexName, options, schemas...).Result()
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(result) // OK
+}

components/indexer/redis/examples/default_indexer/default_indexer.go

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+
+	ri "github.com/cloudwego/eino-ext/components/indexer/redis"
+	"github.com/cloudwego/eino/components/embedding"
+	"github.com/cloudwego/eino/schema"
+	"github.com/redis/go-redis/v9"
+)
+
+// This example is related to example in https://github.com/cloudwego/eino-ext/tree/main/components/retriever/redis/examples/default_retriever
+
+func main() {
+	ctx := context.Background()
+	client := redis.NewClient(&redis.Options{
+		Addr: "localhost:6379",
+	})
+
+	b, err := os.ReadFile("./examples/embeddings.json")
+	if err != nil {
+		panic(err)
+	}
+
+	var dense [][]float64
+	if err = json.Unmarshal(b, &dense); err != nil {
+		panic(err)
+	}
+
+	indexer, err := ri.NewIndexer(ctx, &ri.IndexerConfig{
+		Client:           client,
+		KeyPrefix:        "eino_doc:",
+		DocumentToHashes: nil, // use default convert method
+		BatchSize:        5,
+		Embedding:        &mockEmbedding{dense}, // replace with real embedding
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	contents := `1. Eiffel Tower: Located in Paris, France, it is one of the most famous landmarks in the world, designed by Gustave Eiffel and built in 1889.
+2. The Great Wall: Located in China, it is one of the Seven Wonders of the World, built from the Qin Dynasty to the Ming Dynasty, with a total length of over 20000 kilometers.
+3. Grand Canyon National Park: Located in Arizona, USA, it is famous for its deep canyons and magnificent scenery, which are cut by the Colorado River.
+4. The Colosseum: Located in Rome, Italy, built between 70-80 AD, it was the largest circular arena in the ancient Roman Empire.
+5. Taj Mahal: Located in Agra, India, it was completed by Mughal Emperor Shah Jahan in 1653 to commemorate his wife and is one of the New Seven Wonders of the World.
+6. Sydney Opera House: Located in Sydney Harbour, Australia, it is one of the most iconic buildings of the 20th century, renowned for its unique sailboat design.
+7. Louvre Museum: Located in Paris, France, it is one of the largest museums in the world with a rich collection, including Leonardo da Vinci's Mona Lisa and Greece's Venus de Milo.
+8. Niagara Falls: located at the border of the United States and Canada, consisting of three main waterfalls, its spectacular scenery attracts millions of tourists every year.
+9. St. Sophia Cathedral: located in Istanbul, Türkiye, originally built in 537 A.D., it used to be an Orthodox cathedral and mosque, and now it is a museum.
+10. Machu Picchu: an ancient Inca site located on the plateau of the Andes Mountains in Peru, one of the New Seven Wonders of the World, with an altitude of over 2400 meters.`
+
+	var docs []*schema.Document
+	for idx, str := range strings.Split(contents, "\n") {
+		docs = append(docs, &schema.Document{
+			ID:      strconv.FormatInt(int64(idx+1), 10),
+			Content: str,
+		})
+	}
+
+	ids, err := indexer.Store(ctx, docs)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(ids) // [1 2 3 4 5 6 7 8 9 10]
+	// redis hashes keys are eino_doc:1, eino_doc:2 ...
+}
+
+// mockEmbedding returns embeddings with 1024 dimensions
+type mockEmbedding struct {
+	dense [][]float64
+}
+
+func (m mockEmbedding) EmbedStrings(ctx context.Context, texts []string, opts ...embedding.Option) ([][]float64, error) {
+	return m.dense, nil
+}