接口定义
Upsert()
接口用于给创建的 Collection 中插入 Document。如果 Collection 在创建时,已配置 Embedding 参数,则仅需要插入文本信息,Embedding 服务会自动将文本信息转换为向量数据,存入数据库。Upsert(ctx context.Context, databaseName string, collectionName string, documents interface{}, params ...*tcvectordb.UpsertDocumentParams) (result *tcvectordb.UpsertDocumentResult, err error)
使用示例
如下示例,给集合 go-sdk-test-emcoll 基于文本字段 segment 插入数据。segment 为创建 Collection 时指定的文本字段。
var (ctx = context.Background()database = "go-sdk-test-db"embeddingCollection = "go-sdk-test-emcoll")result, err := client.Upsert(ctx, database, embeddingCollection, []tcvectordb.Document{{Id: "0001",Fields: map[string]tcvectordb.Field{"bookName": {Val: "西游记"},"author": {Val: "吴承恩"},"page": {Val: 21},"text": {Val: "富贵功名,前缘分定,为人切莫欺心。"},},},{Id: "0002",Fields: map[string]tcvectordb.Field{"bookName": {Val: "西游记"},"author": {Val: "吴承恩"},"page": {Val: 22},"text": {Val: "正大光明,忠良善果弥深。些些狂妄天加谴,眼前不遇待时临。"},},},{Id: "0003",Fields: map[string]tcvectordb.Field{"bookName": {Val: "三国演义"},"author": {Val: "罗贯中"},"page": {Val: 23},"text": {Val: "细作探知这个消息,飞报吕布。"},},},{Id: "0004",Fields: map[string]tcvectordb.Field{"bookName": {Val: "三国演义"},"author": {Val: "罗贯中"},"page": {Val: 24},"text": {Val: "布大惊,与陈宫商议。宫曰:“闻刘玄德新领徐州,可往投之。”布从其言,竟投徐州来。有人报知玄德。"},},},{Id: "0005",Fields: map[string]tcvectordb.Field{"bookName": {Val: "三国演义"},"author": {Val: "罗贯中"},"page": {Val: 25},"text": {Val: "玄德曰:“布乃当今英勇之士,可出迎之。”糜竺曰:“吕布乃虎狼之徒,不可收留;收则伤人矣。"},},},})log.Printf("upsert result: %+v", result)
如下示例,给集合 go-sdk-test-coll 直接写入向量数据与稀疏向量,对应字段为 Vector 与 SparseVector。
var (ctx = context.Background()database = "go-sdk-test-db"collectionName = "go-sdk-test-coll")buildIndex := trueresult, err := client.Upsert(ctx, database, collectionName, []tcvectordb.Document{{Id: "0001",Vector: []float32{0.2123, 0.21, 0.213},SparseVector: []encoder.SparseVecItem{{ TermId: 4056151844, Score: 0.7627807, }, { TermId: 4293601821, Score: 0.7627807, }, { TermId: 1834252564, Score: 0.7627807, },},Fields: map[string]tcvectordb.Field{"bookName": {Val: "西游记"},"author": {Val: "吴承恩"},"page": {Val: 21},"segment": {Val: "富贵功名,前缘分定,为人切莫欺心。"},"tag": {Val: []string{"孙悟空", "猪八戒", "唐僧"}},},},{Id: "0002",Vector: []float32{0.2123, 0.22, 0.213},SparseVector: []encoder.SparseVecItem{{ TermId: 4056151844, Score: 0.7627807, }, { TermId: 4293601821, Score: 0.7627807, }, { TermId: 1834252564, Score: 0.7627807, },},Fields: map[string]tcvectordb.Field{"bookName": {Val: "西游记"},"author": {Val: "吴承恩"},"page": {Val: 22},"segment": {Val: "正大光明,忠良善果弥深。些些狂妄天加谴,眼前不遇待时临。"},"tag": {Val: []string{"孙悟空", "猪八戒", "唐僧"}},},},{Id: "0003",Vector: []float32{0.2123, 0.23, 0.213},SparseVector: []encoder.SparseVecItem{{ TermId: 4056151844, Score: 0.7627807, }, { TermId: 4293601821, Score: 0.7627807, }, { TermId: 1834252564, Score: 0.7627807, },},Fields: map[string]tcvectordb.Field{"bookName": {Val: "三国演义"},"author": {Val: "罗贯中"},"page": {Val: 23},"segment": {Val: "细作探知这个消息,飞报吕布。"},"tag": {Val: []string{"曹操", "诸葛亮", "刘备"}},},},},}, &tcvectordb.UpsertDocumentParams{BuildIndex: &buildIndex})log.Printf("upsert result: %+v", result)
var (ctx = context.Background()database = "go-sdk-test-db"collectionName = "go-sdk-test-coll")buildIndex := truebm25, err := encoder.NewBM25Encoder(&encoder.BM25EncoderParams{Bm25Language: "zh"})if err != nil { log.Fatalf(err.Error()) }segments := []string{ "腾讯云向量数据库(Tencent Cloud VectorDB)是一款全托管的自研企业级分布式数据库服务,专用于存储、索引、检索、管理由深度神经网络或其他机器学习模型生成的大量多维嵌入向量。", "作为专门为处理输入向量查询而设计的数据库,它支持多种索引类型和相似度计算方法,单索引支持10亿级向量规模,高达百万级 QPS 及毫秒级查询延迟。", "不仅能为大模型提供外部知识库,提高大模型回答的准确性,还可广泛应用于推荐系统、NLP 服务、计算机视觉、智能客服等 AI 领域。", }// 查看稀疏向量文本拆分情况tokens := bm25.GetTokenizer().Tokenize(segments[0])fmt.Println("tokens: ", tokens)// 如下使用 tcvdb-text 工具的接口 bm25.EncodeTexts 将segments 文本转为稀疏向量表示。sparse_vectors, err := bm25.EncodeTexts(segments) if err != nil { log.Fatalf(err.Error()) }// 写入向量数据、稀疏向量、标量字段result, err1 := client.Upsert(ctx,, database, collectionName, []tcvectordb.Document{{Id: "0001",Vector: []float32{0.2123, 0.21, 0.213},SparseVector: sparse_vectors[0],},{Id: "0002",Vector: []float32{0.2123, 0.22, 0.213},SparseVector: sparse_vectors[1],},{Id: "0003",Vector: []float32{0.2123, 0.23, 0.213},SparseVector: sparse_vectors[2],},},}, &tcvectordb.UpsertDocumentParams{BuildIndex: &buildIndex})
入参描述
参数名称 | 参数含义 | 子参数 | 是否必选 | 配置方法 |
databaseName | 指定需写入的数据库名 | - | 是 | Database 命名要求如下: 只能使用英文字母,数字,下划线_、中划线-,并以英文字母开头。 长度要求:[1,128]。 |
collectionName | 指定写入数据的集合 | - | 是 | Collection 命名要求如下: 只能使用英文字母,数字,下划线_、中划线-,并以英文字母开头。 长度要求:[1,128]。 |
BuildIndex
| 是否重建索引 | - | 否 | 取值如下所示: true:需更新索引。默认值是 true。 false:不更新索引。 注意: 如果创建 Collection 选择的索引类型为 IVF 系列: 当第一次写入时,当前集合还没有向量索引,此时 BuildIndex 必须为 false。插入原始数据之后,需通过 rebuild_index() 训练数据并重建索引。 当集合已经调用过 rebuild_index() 创建索引后,集合已经存在向量索引,此时: 如果 BuildIndex = true,表示新写入的数据会加入到已有的 IVF 索引中,但不会更新索引结构,此时新写入的数据可以被检索到。 如果 BuildIndex = false,表示新写入的数据不会加入到已有的 IVF 索引中,此时新写入的数据无法被检索到。 |
Document | 指定要插入的 Document 数据,是一个数组,支持单次插入一条或者多条 Document,最大可插入 1000条。 | Id | 是 | Document 主键,长度限制为[1,128]。 |
| | Vector | 否 | 表示文档的向量值,请务必使用32位浮点数存储向量数据。 说明: 如果业务无需使用腾讯云向量数据库(Tencent Cloud VectorDB)的 Embedding 功能做向量化,则配置该参数,写入向量数据,而无需配置 Embedding 参数 text (创建 Collection 时,Embedding 参数 field 对应指定的文本字段名,示例中为 text)。 |
| |
Fields | 否 | text 字段为创建集合时,Embedding 参数 Field 对应指定的文本字段名,您可以自定义其他便于识别的字段名。 说明: 写入原始文本数据,系统会自动从该字段中提取原始文本信息,并将其转换为向量数据,并将原始文本以及转化后的向量数据一起存储在数据库中。 |
| | | | 其他自定义扩展的标量字段,用于存储文档的其他信息。例如:bookName、author、page。 说明:
若时间戳字段为空未指定具体的过期时间,插入的该条数据将不会执行过期删除操作,数据将永久保留。 若时间戳字段传入 Value 的数据类型有误或者不符合 Unix 时间戳规范时,将会报出错误信息,请根据提示信息修改。 若时间戳字段指定的过期时间小于当前插入数据时的时间,则在下一个定时删除操作时,直接删除该条数据。 |