文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>对象存储>向量存储与检索>向量存储桶>SDK 文档>Go SDK>向量操作>获取向量

获取向量

最近更新时间：2026-04-01 15:41:32

我的收藏

本页目录：

简介

本文档介绍如何使用对象存储 COS 的 Go SDK 从向量索引中获取一个或多个向量的基本信息。

功能说明

GetVectors 方法用于从指定的向量索引中，根据向量主键（Key）列表检索对应的向量数据。您可以选择性地控制是否返回向量数据和元数据。
注意：
单次请求最多可获取100个向量。
如果指定的 Key 不存在，该 Key 不会出现在返回结果中（不会报错）。

方法原型

func (s *VectorService) GetVectors(ctx context.Context, opt *GetVectorsOptions, keys []string) (*GetVectorsResult, *Response, error)

请求参数说明

GetVectorsOptions 结构体字段说明：
参数
描述
类型
是否必填
VectorBucketName
向量桶名称，格式为 <BucketName-APPID>，例如 examplebucket-1250000000。
支持小写字母、数字和 -，长度限制为3-63个字符。
string
是
IndexName
向量索引名称。
string
是
ReturnData
是否返回向量数据。设为 true 则返回向量数据，默认为 false。
*bool
否
ReturnMetadata
是否返回向量元数据。设为 true 则返回元数据，默认为 false。
*bool
否
keys 参数说明：
参数
描述
类型
是否必填
keys
要获取的向量 Key 列表，最大100个。
[]string
是

返回结果说明

调用成功后，将返回 (*GetVectorsResult, *Response, error) 三个值。
GetVectorsResult 结构体字段说明：
参数
描述
类型
Vectors
查询到的向量列表。
[]OutputVector
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.GetVectorsOptions{
        VectorBucketName: bucketName,
        IndexName:        indexName,
        // 不设置 ReturnData 和 ReturnMetadata，默认均为 false
    }

    // 通过 Key 列表获取向量
    keys := []string{"vector-001", "vector-002"}

    res, _, err := client.Vector.GetVectors(context.Background(), opt, keys)
    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)
    }
}

案例二：获取向量数据和元数据

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"

    // 设置 ReturnData 和 ReturnMetadata 为 true
    returnData := true
    returnMetadata := true

    opt := &cos.GetVectorsOptions{
        VectorBucketName: bucketName,
        IndexName:        indexName,
        ReturnData:       &returnData,
        ReturnMetadata:   &returnMetadata,
    }

    keys := []string{"doc-001", "doc-002", "doc-003"}

    res, _, err := client.Vector.GetVectors(context.Background(), opt, keys)
    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 v.Data != nil {
            fmt.Printf("    向量数据 (前3维): %v\\n", v.Data.Float32[:min(3, len(v.Data.Float32))])
        }
        if v.Metadata != nil {
            fmt.Printf("    元数据: %v\\n", v.Metadata)
        }
    }
}

func min(a, b int) int {
    if a < b {
        return a
    }
    return b
}

案例三：仅返回向量数据（不含元数据）

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"

    // 仅返回向量数据，不返回元数据
    returnData := true
    returnMetadata := false

    opt := &cos.GetVectorsOptions{
        VectorBucketName: bucketName,
        IndexName:        indexName,
        ReturnData:       &returnData,
        ReturnMetadata:   &returnMetadata,
    }

    // 批量获取多个向量的数据，用于后续计算或导出
    keys := []string{"vec-a", "vec-b", "vec-c", "vec-d", "vec-e"}

    res, _, err := client.Vector.GetVectors(context.Background(), opt, keys)
    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 条向量数据（共请求 %d 个 Key）\\n", len(res.Vectors), len(keys))
    for _, v := range res.Vectors {
        if v.Data != nil {
            fmt.Printf("  Key: %s, 维度: %d\\n", v.Key, len(v.Data.Float32))
        }
    }
}
中国站