对象存储配置

Lance 支持 AWS S3 (以及兼容存储)、Azure Blob 存储和 Google Cloud Storage 等对象存储。使用哪种对象存储由数据集路径的 URI 方案决定。例如，s3://bucket/path 将使用 S3，az://bucket/path 将使用 Azure，gs://bucket/path 将使用 GCS。

这些对象存储需要额外的配置对象。有两种方法可以指定这些配置：通过设置环境变量，或通过将它们传递给 lance.dataset 和 lance.write_dataset 的 storage_options 参数。例如，要在 shell 中全局设置更高的超时，您可以运行

export TIMEOUT=60s

如果您只想为单个数据集设置超时，您可以将其作为存储选项传递

import lance
ds = lance.dataset("s3://path", storage_options={"timeout": "60s"})

通用配置

这些选项适用于所有对象存储。

键	描述
allow_http	允许非 TLS，即非 HTTPS 连接。默认值为 False。
download_retry_count	下载重试次数。默认值为 3。当 HTTP 请求成功但响应未完全下载时（通常是由于违反 request_timeout），将应用此限制。
allow_invalid_certificates	跳过 HTTPS 连接上的证书验证。默认值为 False。警告：这不安全，应仅用于测试。
connect_timeout	客户端连接阶段的超时时间。默认值为 5s。
request_timeout	整个请求的超时时间，从连接开始直到响应正文完成。默认值为 30s。
user_agent	在请求中使用的用户代理字符串。
proxy_url	用于请求的代理服务器 URL。默认值为 None。
proxy_ca_certificate	用于代理连接的 PEM 格式 CA 证书
proxy_excludes	绕过代理的主机列表。这是一个以逗号分隔的域和 IP 掩码列表。所提供域的任何子域都将被绕过。例如，example.com, 192.168.1.0/24 将绕过 https://api.example.com、https://www.example.com 以及 192.168.1.0/24 范围内的任何 IP。
client_max_retries	S3 客户端重试请求的次数。默认值为 10。
client_retry_timeout	S3 客户端重试请求的超时时间（秒）。默认值为 180。

S3 配置

S3（和 S3 兼容存储）具有额外的配置选项，用于配置授权和 S3 特定功能（如服务器端加密）。

AWS 凭据可以在环境变量 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_SESSION_TOKEN 中设置。或者，它们可以作为参数传递给 storage_options 参数

import lance
ds = lance.dataset(
    "s3://bucket/path",
    storage_options={
        "access_key_id": "my-access-key",
        "secret_access_key": "my-secret-key",
        "session_token": "my-session-token",
    }
)

如果您正在使用 AWS SSO，您可以指定 AWS_PROFILE 环境变量。它不能在 storage_options 参数中指定。

以下键可以用作环境变量或 storage_options 参数中的键

键	描述
aws_region / region	存储桶所在的 AWS 区域。在使用 AWS S3 时可以自动检测，但对于 S3 兼容存储必须指定。
aws_access_key_id / access_key_id	要使用的 AWS 访问密钥 ID。
aws_secret_access_key / secret_access_key	要使用的 AWS 秘密访问密钥。
aws_session_token / session_token	要使用的 AWS 会话令牌。
aws_endpoint / endpoint	用于 S3 兼容存储的端点。
aws_virtual_hosted_style_request / virtual_hosted_style_request	是否使用虚拟托管式请求，其中存储桶名称是端点的一部分。旨在与 aws_endpoint 一起使用。默认值为 False。
aws_s3_express / s3_express	是否使用 S3 Express One Zone 端点。默认值为 False。请参阅下文了解更多详细信息。
aws_server_side_encryption	要使用的服务器端加密算法。必须是 "AES256"、"aws:kms" 或 "aws:kms:dsse" 之一。默认值为 None。
aws_sse_kms_key_id	用于服务器端加密的 KMS 密钥 ID。如果设置，aws_server_side_encryption 必须是 "aws:kms" 或 "aws:kms:dsse"。
aws_sse_bucket_key_enabled	是否为服务器端加密使用存储桶密钥。

S3 兼容存储

Lance 还可以连接到 S3 兼容存储，例如 MinIO。为此，您必须同时指定区域和端点

import lance
ds = lance.dataset(
    "s3://bucket/path",
    storage_options={
        "region": "us-east-1",
        "endpoint": "http://minio:9000",
    }
)

这也可以通过 AWS_ENDPOINT 和 AWS_DEFAULT_REGION 环境变量来完成。

S3 Express (目录存储桶)

Lance 支持 S3 Express One Zone 存储桶，又称 S3 目录存储桶。S3 Express 存储桶仅支持从同一区域内的 EC2 实例进行连接。默认情况下，Lance 会自动识别 Express 存储桶的 --x-s3 后缀，无需特殊配置。

在访问点或隐藏存储桶名称的私有链接的情况下，您可以通过存储选项 s3_express 明确配置 Express 存储桶访问。

import lance
ds = lance.dataset(
    "s3://my-bucket--use1-az4--x-s3/path/imagenet.lance",
    storage_options={
        "region": "us-east-1",
        "s3_express": "true",
    }
)

Google Cloud Storage 配置

GCS 凭据通过将 GOOGLE_SERVICE_ACCOUNT 环境变量设置为包含服务帐户凭据的 JSON 文件的路径来配置。或者，您可以通过 storage_options 传递 JSON 文件的路径

import lance
ds = lance.dataset(
    "gs://my-bucket/my-dataset",
    storage_options={
        "service_account": "path/to/service-account.json",
    }
)

注意

默认情况下，GCS 使用 HTTP/1 进行通信，而不是 HTTP/2。这显著提高了最大吞吐量。但是，如果您由于某种原因希望使用 HTTP/2，您可以将环境变量 HTTP1_ONLY 设置为 false。

以下键可以用作环境变量或 storage_options 参数中的键

键	描述
google_service_account / service_account	服务帐户 JSON 文件的路径。
google_service_account_key / service_account_key	序列化的服务帐户密钥。
google_application_credentials / application_credentials	应用程序凭据的路径。

Azure Blob Storage 配置

Azure Blob Storage 凭据可以通过设置 AZURE_STORAGE_ACCOUNT_NAME 和 AZURE_STORAGE_ACCOUNT_KEY 环境变量来配置。或者，您可以通过 storage_options 参数传递帐户名和密钥

import lance
ds = lance.dataset(
    "az://my-container/my-dataset",
    storage_options={
        "account_name": "some-account",
        "account_key": "some-key",
    }
)

这些键可以用作环境变量或 storage_options 参数中的键

键	描述
azure_storage_account_name / account_name	Azure 存储帐户的名称。
azure_storage_account_key / account_key	序列化的服务帐户密钥。
azure_client_id / client_id	用于授权请求的服务主体客户端 ID。
azure_client_secret / client_secret	用于授权请求的服务主体客户端密钥。
azure_tenant_id / tenant_id	OAuth 流中使用的租户 ID。
azure_storage_sas_key / azure_storage_sas_token / sas_key / sas_token	共享访问签名。签名应进行百分比编码，就像在 Azure 存储资源管理器或 Azure 门户中提供的那样。
azure_storage_token / bearer_token / token	持有者令牌。
azure_storage_use_emulator / object_store_use_emulator / use_emulator	将对象存储与 Azurite 存储模拟器一起使用。
azure_endpoint / endpoint	覆盖用于与 Blob 存储通信的端点。
azure_use_fabric_endpoint / use_fabric_endpoint	将对象存储与 URL 方案 account.dfs.fabric.microsoft.com 一起使用。
azure_msi_endpoint / azure_identity_endpoint / identity_endpoint / msi_endpoint	请求 IMDS 托管身份令牌的端点。
azure_object_id / object_id	用于托管身份验证的对象 ID。
azure_msi_resource_id / msi_resource_id	用于托管身份验证的 MSI 资源 ID。
azure_federated_token_file / federated_token_file	包含 Azure AD 工作负载身份联合令牌的文件。
azure_use_azure_cli / use_azure_cli	使用 Azure CLI 获取访问令牌。
azure_disable_tagging / disable_tagging	禁用对象标记。如果后端存储不支持，这可能是可取的。