对象存储配置¶

Lance支持多种对象存储服务，如AWS S3（及兼容存储）、Azure Blob存储和Google云存储。具体使用哪种对象存储取决于数据集路径的URI方案。例如，s3://bucket/path将使用S3，az://bucket/path将使用Azure，而gs://bucket/path将使用GCS。

在版本0.10.7中新增：直接传递选项到存储选项。

这些对象存储需要额外的配置对象。有两种方式来指定这些配置：通过设置环境变量，或者将它们传递给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¶

在0.9.7版本中添加。

Lance支持S3 Express One Zone端点，但需要额外配置。此外， S3 Express端点仅支持从同一区域的EC2实例进行连接

要配置Lance使用S3 Express终端节点，您必须设置存储选项s3_express。表URI中的存储桶名称必须包含后缀。

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云存储配置¶

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存储配置¶

可以通过设置AZURE_STORAGE_ACCOUNT_NAME和AZURE_STORAGE_ACCOUNT_KEY环境变量来配置Azure Blob存储凭据。或者，您可以在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`	Bearer令牌。
`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`	禁用对象标记功能。如果底层存储不支持此功能，禁用可能更为合适。