对象存储列举向量

简介
本文档介绍如何使用对象存储 COS 的 Go SDK 列出指定向量索引中的向量基本信息。
功能说明
ListVectors 方法用于列出指定向量索引中的向量列表。支持分页查询、控制返回数量，以及并行分段列举以提升大规模数据遍历效率。您可以选择性地控制是否返回向量数据和元数据。
方法原型
func (s *VectorService) ListVectors(ctx context.Context, opt *ListVectorsOptions) (*ListVectorsResult, *Response, error)
请求参数说明
ListVectorsOptions 结构体字段说明：
参数
描述
类型
是否必填
VectorBucketName
向量桶名称，格式为 <BucketName-APPID>，例如 examplebucket-1250000000。支持小写字母、数字和 -，长度限制为3-63个字符。
string
是
IndexName
向量索引名称。
string
是
MaxResults
返回的最大向量数量。默认值为500，取值范围为1-1000。
int
否
NextToken
分页查询凭证，来源于上一次 ListVectors 请求的响应。首次调用时留空。
string
否
ReturnData
是否返回向量数据。默认为 false。
*bool
否
ReturnMetadata
是否返回向量元数据。默认为 false。
*bool
否
SegmentCount
并行列举时，表示划分向量的段数。若设置为1则为串行列举。取值范围为1-16。需与 SegmentIndex 同时指定。
int
否
SegmentIndex
并行列举时，表示当前请求列举的向量段的索引（从 0 开始）。取值需小于 SegmentCount。需与 SegmentCount 同时指定。
int
否
返回结果说明
调用成功后，将返回 (*ListVectorsResult, *Response, error) 三个值。
ListVectorsResult 结构体字段说明：
参数
描述
类型
Vectors
向量列表。
[]OutputVector
NextToken
下一页的分页标记。如果为空，表示已到达最后一页。
string
OutputVector 结构体字段说明：
参数
描述
类型
Key
向量主键。
string
Data
向量数据（仅当请求中 ReturnData 为 true 时返回）。
*VectorData
Metadata
向量元数据（仅当请求中 ReturnMetadata 为 true 时返回）。
map[string]interface{}
其他返回值说明：
返回值
描述
类型
resp
响应头信息，包含 HTTP 响应的详细对象等。
*cos.Response
err
错误信息。如果请求成功，返回 nil。
error
如果请求失败，将返回非 nil 的 error。向量检索相关的业务错误（如资源不存在等）会封装为 *cos.VectorErrorResponse 结构，您可以通过 cos.IsVectorError() 辅助函数判断并获取详细错误信息。详细的错误处理方式、VectorErrorResponse 结构体说明及服务端错误码列表请参见 异常处理 文档。
使用案例
案例一：基础列举向量
package main
﻿
import (
    "context"
    "fmt"
    "net/http"
    "os"
﻿
    cos "github.com/tencentyun/cos-go-sdk-v5"
)
﻿
func main() {
    vectorURL, _ := cos.NewVectorURL("ap-guangzhou", true)
﻿
    client := cos.NewClient(&cos.BaseURL{VectorURL: vectorURL}, &http.Client{
        Transport: &cos.AuthorizationTransport{
            SecretID:  os.Getenv("COS_VECTORS_SECRET_ID"),
            SecretKey: os.Getenv("COS_VECTORS_SECRET_KEY"),
        },
    })
﻿
    bucketName := "examplebucket-1250000000"
    indexName := "my-index"
﻿
    opt := &cos.ListVectorsOptions{
        VectorBucketName: bucketName,
        IndexName:        indexName,
        MaxResults:       10,
    }
﻿
    res, _, err := client.Vector.ListVectors(context.Background(), opt)
    if err != nil {
        if vecErr, ok := cos.IsVectorError(err); ok {
            fmt.Printf("向量服务错误，错误码: %s, 错误信息: %s, 请求ID: %s\\n",
                vecErr.Code, vecErr.Message, vecErr.RequestID)
        } else {
            fmt.Printf("请求失败: %v\\n", err)
        }
        return
    }
﻿
    fmt.Printf("成功列举 %d 条向量\\n", len(res.Vectors))
    for _, v := range res.Vectors {
        fmt.Printf("  Key: %s\\n", v.Key)
    }
    if res.NextToken != "" {
        fmt.Printf("还有更多数据，NextToken: %s\\n", res.NextToken)
    }
}
案例二：分页遍历所有向量
package main
﻿
import (
    "context"
    "fmt"
    "net/http"
    "os"
﻿
    cos "github.com/tencentyun/cos-go-sdk-v5"
)
﻿
func main() {
    vectorURL, _ := cos.NewVectorURL("ap-guangzhou", true)
﻿
    client := cos.NewClient(&cos.BaseURL{VectorURL: vectorURL}, &http.Client{
        Transport: &cos.AuthorizationTransport{
            SecretID:  os.Getenv("COS_VECTORS_SECRET_ID"),
            SecretKey: os.Getenv("COS_VECTORS_SECRET_KEY"),
        },
    })
﻿
    bucketName := "examplebucket-1250000000"
    indexName := "my-index"
    returnMetadata := true
﻿
    totalCount := 0
    nextToken := ""
﻿
    for {
        opt := &cos.ListVectorsOptions{
            VectorBucketName: bucketName,
            IndexName:        indexName,
            MaxResults:       100,
            NextToken:        nextToken,
            ReturnMetadata:   &returnMetadata,
        }
﻿
        res, _, err := client.Vector.ListVectors(context.Background(), opt)
        if err != nil {
            if vecErr, ok := cos.IsVectorError(err); ok {
                fmt.Printf("向量服务错误，错误码: %s, 错误信息: %s, 请求ID: %s\\n",
                    vecErr.Code, vecErr.Message, vecErr.RequestID)
            } else {
                fmt.Printf("请求失败: %v\\n", err)
            }
            return
        }
﻿
        totalCount += len(res.Vectors)
        fmt.Printf("本页获取 %d 条向量（累计 %d 条）\\n", len(res.Vectors), totalCount)
﻿
        for _, v := range res.Vectors {
            fmt.Printf("  Key: %s, 元数据: %v\\n", v.Key, v.Metadata)
        }
﻿
        // 如果 NextToken 为空，表示已到达最后一页
        if res.NextToken == "" {
            break
        }
        nextToken = res.NextToken
    }
﻿
    fmt.Printf("遍历完成，共 %d 条向量\\n", totalCount)
}
案例三：并行分段列举（适用于大规模数据）
package main
﻿
import (
    "context"
    "fmt"
    "net/http"
    "os"
    "sync"
﻿
    cos "github.com/tencentyun/cos-go-sdk-v5"
)
﻿
func main() {
    vectorURL, _ := cos.NewVectorURL("ap-guangzhou", true)
﻿
    client := cos.NewClient(&cos.BaseURL{VectorURL: vectorURL}, &http.Client{
        Transport: &cos.AuthorizationTransport{
            SecretID:  os.Getenv("COS_VECTORS_SECRET_ID"),
            SecretKey: os.Getenv("COS_VECTORS_SECRET_KEY"),
        },
    })
﻿
    bucketName := "examplebucket-1250000000"
    indexName := "my-index"
﻿
    // 将数据划分为 4 段，并行列举
    segmentCount := 4
﻿
    var wg sync.WaitGroup
    var mu sync.Mutex
    totalCount := 0
﻿
    for i := 0; i < segmentCount; i++ {
        wg.Add(1)
        go func(segIdx int) {
            defer wg.Done()
﻿
            segCount := 0
            nextToken := ""
﻿
            for {
                opt := &cos.ListVectorsOptions{
                    VectorBucketName: bucketName,
                    IndexName:        indexName,
                    MaxResults:       500,
                    NextToken:        nextToken,
                    SegmentCount:     segmentCount,
                    SegmentIndex:     segIdx,
                }
﻿
                res, _, err := client.Vector.ListVectors(context.Background(), opt)
                if err != nil {
                    if vecErr, ok := cos.IsVectorError(err); ok {
                        fmt.Printf("[段%d] 向量服务错误，错误码: %s, 错误信息: %s\\n",
                            segIdx, vecErr.Code, vecErr.Message)
                    } else {
                        fmt.Printf("[段%d] 请求失败: %v\\n", segIdx, err)
                    }
                    return
                }
﻿
                segCount += len(res.Vectors)
﻿
                if res.NextToken == "" {
                    break
                }
                nextToken = res.NextToken
            }
﻿
            mu.Lock()
            totalCount += segCount
            mu.Unlock()
            fmt.Printf("[段%d] 列举完成，获取 %d 条向量\\n", segIdx, segCount)
        }(i)
    }
﻿
    wg.Wait()
    fmt.Printf("并行列举完成，共 %d 条向量\\n", totalCount)
}
﻿

参数	描述	类型	是否必填
VectorBucketName	向量桶名称，格式为 `<BucketName-APPID>`，例如 `examplebucket-1250000000`。支持小写字母、数字和 `-`，长度限制为3-63个字符。	string	是
IndexName	向量索引名称。	string	是
MaxResults	返回的最大向量数量。默认值为500，取值范围为1-1000。	int	否
NextToken	分页查询凭证，来源于上一次 ListVectors 请求的响应。首次调用时留空。	string	否
ReturnData	是否返回向量数据。默认为 `false`。	*bool	否
ReturnMetadata	是否返回向量元数据。默认为 `false`。	*bool	否
SegmentCount	并行列举时，表示划分向量的段数。若设置为1则为串行列举。取值范围为1-16。需与 `SegmentIndex` 同时指定。	int	否
SegmentIndex	并行列举时，表示当前请求列举的向量段的索引（从 0 开始）。取值需小于 `SegmentCount`。需与 `SegmentCount` 同时指定。	int	否

返回值	描述	类型
resp	响应头信息，包含 HTTP 响应的详细对象等。	*cos.Response
err	错误信息。如果请求成功，返回 `nil`。	error

列举向量

本页目录：

简介

功能说明

方法原型

请求参数说明

返回结果说明

使用案例

案例一：基础列举向量

案例二：分页遍历所有向量

案例三：并行分段列举（适用于大规模数据）