@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/unstructured_etl_python_api.md

@@ -0,0 +1,896 @@
+# 云器 Lakehouse Unstructured ETL Python API 参考文档
+
+## 架构概览
+
+### 系统组件关系
+
+系统采用分层架构，各组件职责清晰：
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    Application Layer                     │
+│    RAG    KB    Search    BI    DataSci    APIs          │
+└──────────────────────────────────────────────────────────┘
+                            ↓
+┌──────────────────────────────────────────────────────────┐
+│                  ETL Processing Layer                    │
+│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐  │
+│ │Unstructured │ │ DashScope   │ │   Data Pipeline     │  │
+│ │             │ │             │ │                     │  │
+│ │  Doc Parse  │ │  Embedding  │ │      Quality        │  │
+│ │  Chunking   │ │  4 Models   │ │     Transform       │  │
+│ │  Multi-Src  │ │   Batch     │ │     Metadata        │  │
+│ └─────────────┘ └─────────────┘ └─────────────────────┘  │
+└──────────────────────────────────────────────────────────┘
+                            ↓
+┌──────────────────────────────────────────────────────────┐
+│               Yunqi Lakehouse Platform                   │
+│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐  │
+│ │Compute Layer│ │Storage Layer│ │   Service Layer     │  │
+│ │             │ │             │ │                     │  │
+│ │ General VC  │ │ User Volume │ │     Metadata        │  │
+│ │ Analytics   │ │ Table Vol   │ │   Access Ctrl       │  │
+│ │ Integration │ │ Named Vol   │ │   Scheduling        │  │
+│ │ Vector Idx  │ │ SQL Storage │ │   Monitoring        │  │
+│ └─────────────┘ └─────────────┘ └─────────────────────┘  │
+└──────────────────────────────────────────────────────────┘
+```
+
+### 数据流模式
+
+#### 1. 批量ETL模式
+```
+┌─────────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
+│Volume Source│→ │  Index   │→ │ Download │→ │Document  │→ │ Chunk    │→ │ Vector   │→ │SQL Store │
+│             │  │  Scan    │  │          │  │ Parse    │  │Process   │  │Generate  │  │          │
+│ File Scan   │  │Metadata  │  │ Local    │  │ Doc      │  │ Text     │  │ Vector   │  │ Table    │
+│ Recursive   │  │Extract   │  │ Cache    │  │ Split    │  │ Blocks   │  │Generate  │  │ Insert   │
+└─────────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘
+```
+- **适用场景**: 大批量文档处理、离线数据湖构建
+- **计算资源**: 通用型 VCluster + 大规格 CRU
+- **存储模式**: Named Volume → SQL 表 + 向量列
+
+#### 2. 实时流处理模式
+```
+┌─────────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
+│Stream Source│→ │ Receive  │→ │ Process  │→ │Vectorize │→ │ Update   │→ │ Search   │
+│             │  │          │  │          │  │          │  │          │  │          │
+│Stream Input │  │ Buffer   │  │Increment │  │Embedding │  │ Live     │  │ Online   │
+│ Data Feed   │  │ Queue    │  │Transform │  │Generate  │  │ Sync     │  │Retrieval │
+└─────────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘
+```
+- **适用场景**: 实时知识库更新、在线 RAG 系统
+- **计算资源**: 分析型 VCluster + 多实例弹缩
+- **存储模式**: Table Volume + 实时 SQL 更新
+
+#### 3. 混合处理模式
+```
+┌─────────────┐
+│Batch Process│ ┐
+│             │ │  ┌──────────────────┐    ┌──────────────┐
+│Historical   │ ├─→│ Unified Vector   │ ──→│ Hybrid       │
+│Data Process │ │  │ Space            │    │ Search       │
+└─────────────┘ │  │                  │    │              │
+┌─────────────┐ │  │ Combined         │    │ Vector +     │
+│Stream Update│ ┘  │ Vector Index     │    │ Text Search  │
+│             │    │                  │    │              │
+│Real-time    │    └──────────────────┘    └──────────────┘
+│Process      │
+└─────────────┘
+```
+- **适用场景**: 企业级知识管理、智能客服系统
+- **计算资源**: 多类型 VCluster 协同工作
+- **存储模式**: 多层 Volume + 统一 SQL 视图
+
+## 核心类和接口
+
+### 云器 Lakehouse SQL 连接器
+
+#### ClickzettaConnectionConfig
+
+数据库连接配置类。
+
+```python
+class ClickzettaConnectionConfig(SqlConnectionConfig):
+    """云器 Lakehouse 数据库连接配置"""
+
+    def __init__(
+        self,
+        service: Optional[str] = None,
+        username: Optional[str] = None,
+        workspace: Optional[str] = None,
+        vcluster: Optional[str] = None,
+        schema: Optional[str] = None,
+        instance: Optional[str] = None,
+        access_config: Optional[ClickzettaAccessConfig] = None
+    ):
+        """
+        Args:
+            service: 云器 Lakehouse 服务地址
+            username: 用户名
+            workspace: 工作空间名称
+            vcluster: 虚拟集群名称
+            schema: 数据库模式名称
+            instance: 实例名称
+            access_config: 访问配置（包含密码等敏感信息）
+        """
+```
+
+**方法：**
+
+- `get_session() -> Session`: 创建数据库会话
+- `wrap_error(e: Exception) -> Exception`: 包装异常信息
+
+#### ClickzettaIndexerConfig
+
+索引器配置类，用于定义数据提取参数。
+
+```python
+class ClickzettaIndexerConfig(SqlIndexerConfig):
+    """云器 Lakehouse 索引器配置"""
+
+    table_name: str  # 表名
+    id_column: str = "id"  # 主键列名
+    batch_size: int = 1000  # 批处理大小
+    where_clause: Optional[str] = None  # WHERE 条件子句
+```
+
+#### ClickzettaIndexer
+
+数据索引器，用于按批次获取数据。
+
+```python
+class ClickzettaIndexer(SqlIndexer):
+    """云器 Lakehouse 数据索引器"""
+
+    def run(self) -> Generator[FileData, None, None]:
+        """
+        运行索引器，按批次返回数据
+
+        Yields:
+            FileData: 每个批次的文件数据对象
+        """
+```
+
+#### ClickzettaDownloaderConfig
+
+下载器配置类。
+
+```python
+class ClickzettaDownloaderConfig(SqlDownloaderConfig):
+    """云器 Lakehouse 下载器配置"""
+
+    fields: List[str]  # 要下载的字段列表
+    download_dir: Path  # 下载目录
+    where_clause: Optional[str] = None  # 额外的WHERE条件
+```
+
+#### ClickzettaDownloader
+
+数据下载器，将索引的数据下载到本地。
+
+```python
+class ClickzettaDownloader(SqlDownloader):
+    """云器 Lakehouse 数据下载器"""
+
+    def run(self, file_data: FileData) -> List[Dict[str, Any]]:
+        """
+        下载指定批次的数据
+
+        Args:
+            file_data: 索引器返回的文件数据对象
+
+        Returns:
+            List[Dict]: 下载的数据记录列表
+        """
+
+    async def run_async(self, file_data: FileData) -> List[Dict[str, Any]]:
+        """异步版本的下载方法"""
+```
+
+#### ClickzettaUploaderConfig
+
+上传器配置类。
+
+```python
+class ClickzettaUploaderConfig(SqlUploaderConfig):
+    """云器 Lakehouse 上传器配置"""
+
+    table_name: str  # 目标表名
+    batch_size: int = 100  # 批量上传大小
+    vector_column: Optional[str] = None  # 向量列名
+    vector_dimension: Optional[int] = None  # 向量维度
+    create_table_if_not_exists: bool = True  # 自动创建表
+```
+
+#### ClickzettaUploader
+
+数据上传器，将处理后的数据上传到云器 Lakehouse。
+
+```python
+class ClickzettaUploader(SqlUploader):
+    """云器 Lakehouse 数据上传器"""
+
+    def upload_batch(self, data: List[Dict[str, Any]]) -> None:
+        """
+        批量上传数据
+
+        Args:
+            data: 要上传的数据记录列表
+        """
+
+    async def upload_batch_async(self, data: List[Dict[str, Any]]) -> None:
+        """异步批量上传"""
+
+    def _upload_data_batch(
+        self,
+        data: List[Dict[str, Any]],
+        file_data: FileData
+    ) -> None:
+        """内部批量上传方法"""
+```
+
+### 云器 Lakehouse Volume 连接器
+
+#### ClickzettaVolumeConnectionConfig
+
+Volume 连接配置类。
+
+```python
+class ClickzettaVolumeConnectionConfig(FsspecConnectionConfig):
+    """云器 Lakehouse Volume 连接配置"""
+
+    def get_client(self, protocol: str = "s3") -> Generator[Session, None, None]:
+        """
+        获取云器 Lakehouse 会话客户端
+
+        Args:
+            protocol: 协议类型（默认 s3）
+
+        Yields:
+            Session: 云器 Lakehouse 会话对象
+        """
+```
+
+#### ClickzettaVolumeIndexerConfig
+
+Volume 索引器配置类。
+
+```python
+class ClickzettaVolumeIndexerConfig(FsspecIndexerConfig):
+    """云器 Lakehouse Volume 索引器配置"""
+
+    index_volume_type: str  # Volume 类型: 'user', 'table', 'named'
+    index_volume_name: Optional[str] = None  # Volume 名称
+    index_remote_path: Optional[str] = None  # 远程路径
+    index_regexp: Optional[str] = None  # 正则表达式过滤
+
+    @property
+    def volume(self) -> str:
+        """构建完整的 volume 标识符"""
+```
+
+**Volume 类型说明：**
+
+- `user`: 用户个人 Volume，不需要 index_volume_name
+- `table`: 表关联 Volume，需要指定表名作为 index_volume_name
+- `named`: 命名 Volume，需要指定卷名作为 index_volume_name
+
+#### ClickzettaVolumeIndexer
+
+Volume 文件索引器。
+
+```python
+class ClickzettaVolumeIndexer(FsspecIndexer):
+    """云器 Lakehouse Volume 文件索引器"""
+
+    def list_files(self) -> List[Dict[str, Any]]:
+        """
+        列举 Volume 中的文件
+
+        Returns:
+            List[Dict]: 文件信息列表，包含 name, path, size, last_modified 等字段
+        """
+
+    def get_file_info(self) -> List[Dict[str, Any]]:
+        """获取文件信息，list_files 的别名"""
+```
+
+#### ClickzettaVolumeDownloaderConfig
+
+Volume 下载器配置类。
+
+```python
+class ClickzettaVolumeDownloaderConfig(FsspecDownloaderConfig):
+    """云器 Lakehouse Volume 下载器配置"""
+
+    download_volume_type: Optional[str] = None  # Volume 类型: 'user', 'table', 'named'
+    download_volume_name: Optional[str] = None  # Volume 名称
+    download_remote_path: Optional[str] = None  # 远程路径
+    remote_url: Optional[str] = None   # 远程 URL
+    download_regexp: Optional[str] = None       # 正则表达式过滤
+
+    @property
+    def volume(self) -> str:
+        """构建完整的volume标识符"""
+        # 自动根据 download_volume_type 和 download_volume_name 构建
+```
+
+#### ClickzettaVolumeDownloader
+
+Volume 文件下载器，支持智能错误处理和路径修复。
+
+```python
+class ClickzettaVolumeDownloader(FsspecDownloader):
+    """云器 Lakehouse Volume 文件下载器"""
+
+    def download_file(
+        self,
+        remote_path: str,
+        local_path: str,
+        file_info: Optional[Dict] = None
+    ) -> None:
+        """
+        下载单个文件
+
+        Args:
+            remote_path: 远程文件路径
+            local_path: 本地保存路径
+            file_info: 文件信息字典（用于自动推断 volume）
+
+        Raises:
+            FileNotFoundError: 文件不存在于 Volume 中
+            Exception: 下载过程中发生错误
+
+        注意:
+            - 自动处理 ClickZetta 创建目录而非文件的情况
+            - 智能检测并处理 XML 错误响应
+            - 确保下载路径的正确性
+        """
+
+    def run(
+        self,
+        files: Optional[List[Dict[str, Any]]] = None,
+        **kwargs
+    ) -> List[Dict[str, Any]]:
+        """
+        批量下载文件
+
+        Args:
+            files: 要下载的文件列表
+
+        Returns:
+            List[Dict]: 下载结果列表，包含:
+                - remote_path: 远程文件路径
+                - local_path: 本地文件路径
+                - status: 'success' 或 'failed'
+                - error: 错误信息（如果失败）
+        """
+```
+
+#### ClickzettaVolumeUploaderConfig
+
+Volume 上传器配置类。
+
+```python
+class ClickzettaVolumeUploaderConfig(FsspecUploaderConfig):
+    """云器 Lakehouse Volume 上传器配置"""
+
+    volume_type: Optional[str] = None  # Volume 类型: 'user', 'table', 'named'
+    volume_name: Optional[str] = None  # Volume 名称
+    remote_path: Optional[str] = None  # 远程路径
+    remote_url: Optional[str] = None   # 远程 URL
+    regexp: Optional[str] = None       # 正则表达式过滤
+
+    def __init__(self, **data):
+        """初始化配置，自动构建 remote_url"""
+        # 如果未提供 remote_url，会根据 volume_type、volume_name 和 remote_path 自动构建
+
+    @property
+    def volume(self) -> str:
+        """构建完整的volume标识符"""
+        # 自动根据 volume_type 和 volume_name 构建
+```
+
+#### ClickzettaVolumeUploader
+
+Volume 文件上传器。
+
+```python
+class ClickzettaVolumeUploader(FsspecUploader):
+    """云器 Lakehouse Volume 文件上传器"""
+
+    def upload_file(
+        self,
+        local_path: str,
+        remote_path: Optional[str] = None
+    ) -> None:
+        """
+        上传单个文件
+
+        Args:
+            local_path: 本地文件路径
+            remote_path: 远程保存路径
+        """
+```
+
+#### ClickzettaVolumeDeleterConfig
+
+Volume 删除器配置类。
+
+```python
+class ClickzettaVolumeDeleterConfig:
+    """云器 Lakehouse Volume 删除器配置"""
+
+    delete_volume_type: Optional[str] = None  # Volume 类型: 'user', 'table', 'named'
+    delete_volume_name: Optional[str] = None  # Volume 名称
+
+    @property
+    def volume(self) -> str:
+        """构建完整的volume标识符"""
+        # 自动根据 delete_volume_type 和 delete_volume_name 构建
+```
+
+#### ClickzettaVolumeDeleter
+
+Volume 文件删除器，支持彻底删除文件。
+
+```python
+class ClickzettaVolumeDeleter:
+    """云器 Lakehouse Volume 文件删除器"""
+
+    def delete_file(self, file_path: str) -> bool:
+        """
+        删除指定文件
+
+        Args:
+            file_path: 要删除的文件路径
+
+        Returns:
+            bool: 删除是否成功
+
+        注意:
+            - 删除操作是永久性的，无法恢复
+            - 删除后文件将从索引中消失，无法再被下载或访问
+            - 支持删除各种路径格式的文件
+        """
+
+    def delete_directory(self, directory_path: str) -> bool:
+        """删除指定目录及其所有内容"""
+
+    def delete_all(self) -> bool:
+        """删除 Volume 中的所有内容"""
+```
+
+### Volume 连接器使用示例
+
+#### 完整的 Volume 操作流程
+
+以下示例展示了如何正确使用修复后的 Volume 连接器：
+
+```python
+import tempfile
+from pathlib import Path
+from unstructured_ingest.processes.connectors.fsspec.clickzetta_volume import *
+
+# 1. 创建连接配置
+config = ClickzettaVolumeConnectionConfig(
+    access_config=ClickzettaVolumeAccessConfig()
+)
+
+# 2. 索引操作 - 列出文件
+indexer = ClickzettaVolumeIndexer(
+    connection_config=config,
+    index_config=ClickzettaVolumeIndexerConfig(
+        index_volume_type="user",  # 或 "table", "named"
+        index_volume_name=None,    # table/named volume 需要指定名称
+        index_remote_path="docs/", # 可选：指定子目录
+        index_regexp=r".*\.pdf$"   # 可选：正则过滤
+    )
+)
+files = indexer.list_files()
+
+# 3. 下载操作 - 智能错误处理
+with tempfile.TemporaryDirectory() as temp_dir:
+    downloader = ClickzettaVolumeDownloader(
+        connection_config=config,
+        download_config=ClickzettaVolumeDownloaderConfig(
+            download_volume_type="user",
+            download_dir=temp_dir,
+            # 其他字段会自动继承或推断
+        )
+    )
+    results = downloader.run(files[:3])  # 下载前3个文件
+
+    for result in results:
+        if result["status"] == "success":
+            print(f"下载成功: {result['local_path']}")
+        else:
+            print(f"下载失败: {result['error']}")
+
+# 4. 上传操作 - 自动构建 remote_url
+test_file = Path("test.txt")
+test_file.write_text("测试内容")
+
+uploader = ClickzettaVolumeUploader(
+    connection_config=config,
+    upload_config=ClickzettaVolumeUploaderConfig(
+        volume_type="user",
+        remote_path="uploaded_test.txt"
+        # remote_url 会自动构建
+    )
+)
+uploader.upload_file(str(test_file), "uploaded_test.txt")
+
+# 5. 删除操作 - 彻底删除验证
+deleter = ClickzettaVolumeDeleter(
+    connection_config=config,
+    deleter_config=ClickzettaVolumeDeleterConfig(
+        delete_volume_type="user"
+    )
+)
+success = deleter.delete_file("uploaded_test.txt")
+print(f"删除结果: {success}")
+
+# 6. 验证删除效果
+files_after = indexer.list_files()
+remaining = [f for f in files_after if f["name"] == "uploaded_test.txt"]
+print(f"删除后剩余文件: {len(remaining)}")  # 应该为 0
+```
+
+#### 关键改进说明
+
+1. **配置类字段完整性**: 所有配置类现在包含必要的字段
+2. **路径处理修复**: 修复了字符串和 Path 对象拼接问题
+3. **智能错误处理**: 自动检测和处理 XML 错误响应
+4. **目录vs文件修复**: 正确处理 ClickZetta 创建目录的情况
+5. **删除功能验证**: 确保删除操作的完整性和正确性
+
+### DashScope 嵌入服务
+
+#### DashScopeEmbeddingConfig
+
+DashScope 嵌入配置类。
+
+```python
+class DashScopeEmbeddingConfig(EmbeddingConfig):
+    """DashScope 嵌入服务配置"""
+
+    model_name: str = "text-embedding-v3"  # 模型名称
+    api_key: Optional[str] = None  # API 密钥
+    batch_size: int = 25  # 批处理大小
+    max_retries: int = 3  # 最大重试次数
+    retry_delay: float = 1.0  # 重试延迟（秒）
+    text_field: str = "content"  # 文本字段名
+    dimensions: Optional[int] = None  # 向量维度
+```
+
+**支持的模型：**
+
+| 模型名 | 维度 | 最大输入长度 |
+|--------|------|-------------|
+| text-embedding-v1 | 1536 | 2048 tokens |
+| text-embedding-v2 | 1536 | 2048 tokens |
+| text-embedding-v3 | 1024 | 8192 tokens |
+| text-embedding-v4 | 1024 | 8192 tokens |
+
+#### DashScopeEmbedder
+
+DashScope 嵌入器实现类。
+
+```python
+class DashScopeEmbedder(BaseEmbedder):
+    """DashScope 嵌入器"""
+
+    def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        """
+        为文档列表生成嵌入向量
+
+        Args:
+            texts: 要嵌入的文本列表
+
+        Returns:
+            List[List[float]]: 嵌入向量列表
+        """
+
+    def embed_query(self, text: str) -> List[float]:
+        """
+        为查询文本生成嵌入向量
+
+        Args:
+            text: 查询文本
+
+        Returns:
+            List[float]: 嵌入向量
+        """
+
+    async def embed_documents_async(self, texts: List[str]) -> List[List[float]]:
+        """异步版本的文档嵌入"""
+
+    async def embed_query_async(self, text: str) -> List[float]:
+        """异步版本的查询嵌入"""
+```
+
+## 工具函数
+
+### Volume 工具函数
+
+#### build_remote_url
+
+```python
+def build_remote_url(volume: str, remote_path: Optional[str] = None) -> str:
+    """
+    构建云器 Lakehouse Volume 协议的远程 URL
+
+    Args:
+        volume: Volume 标识符
+        remote_path: 远程路径
+
+    Returns:
+        str: 完整的 Volume URL
+
+    Examples:
+        build_remote_url("user", "docs/file.txt") -> "volume:user://~/docs/file.txt"
+        build_remote_url("table_docs", "images/") -> "volume:table://docs/images/"
+        build_remote_url("shared_volume", "data/") -> "volume://shared_volume/data/"
+    """
+```
+
+#### build_sql
+
+```python
+def build_sql(
+    action: str,
+    volume: str,
+    file_path: Optional[str] = None,
+    is_table: bool = False,
+    is_user: bool = False,
+    regexp: Optional[str] = None
+) -> str:
+    """
+    构建云器 Lakehouse Volume 操作的 SQL 语句
+
+    Args:
+        action: 操作类型 ('list', 'get', 'put', 'remove_file', 'remove_dir', 'remove_all')
+        volume: Volume 标识符
+        file_path: 文件路径
+        is_table: 是否为 Table Volume
+        is_user: 是否为 User Volume
+        regexp: 正则表达式过滤（仅用于 list 操作）
+
+    Returns:
+        str: SQL 语句
+
+    Examples:
+        build_sql("list", "user", "docs/", is_user=True)
+        -> "LIST USER VOLUME SUBDIRECTORY 'docs/'"
+
+        build_sql("get", "table_docs", "file.txt", is_table=True)
+        -> "GET TABLE VOLUME docs FILE 'file.txt' TO '{local_path}'"
+    """
+```
+
+#### get_env_multi
+
+```python
+def get_env_multi(key: str) -> str:
+    """
+    多前缀环境变量查找
+
+    支持的前缀顺序：CLICKZETTA_, CZ_, cz_, 无前缀
+    支持大小写变体
+
+    Args:
+        key: 环境变量基础名称
+
+    Returns:
+        str: 找到的环境变量值，未找到返回 None
+
+    Examples:
+        # 查找顺序：CLICKZETTA_USERNAME, CZ_USERNAME, cz_username, USERNAME,
+        #         CLICKZETTA_username, CZ_username, cz_username, username
+        get_env_multi("username")
+    """
+```
+
+### SQL 工具函数
+
+#### 数据验证函数
+
+```python
+def validate_vector_dimension(vector: List[float], expected_dim: int) -> bool:
+    """验证向量维度是否正确"""
+
+def validate_batch_data(data: List[Dict], required_fields: List[str]) -> bool:
+    """验证批次数据是否包含必需字段"""
+
+def sanitize_table_name(table_name: str) -> str:
+    """清理表名，确保符合 SQL 命名规范"""
+```
+
+## 异常类
+
+### UserAuthError
+
+```python
+class UserAuthError(Exception):
+    """用户认证错误"""
+    # 当云器 Lakehouse 连接认证失败时抛出
+```
+
+### UserError
+
+```python
+class UserError(Exception):
+    """用户操作错误"""
+    # 当用户配置或操作有误时抛出
+```
+
+## 配置示例
+
+### 完整的环境变量配置
+
+```bash
+# 云器 Lakehouse 连接配置
+export CLICKZETTA_SERVICE="https://your-service.clickzetta.com"
+export CLICKZETTA_USERNAME="your_username"
+export CLICKZETTA_PASSWORD="your_password"
+export CLICKZETTA_WORKSPACE="your_workspace"
+export CLICKZETTA_SCHEMA="your_schema"
+export CLICKZETTA_INSTANCE="your_instance"
+export CLICKZETTA_VCLUSTER="your_vcluster"
+
+# DashScope 配置
+export DASHSCOPE_API_KEY="your_dashscope_api_key"
+
+# 可选的性能配置
+export CLICKZETTA_POOL_SIZE="10"
+export DASHSCOPE_RATE_LIMIT="100"
+export BATCH_SIZE="1000"
+export MAX_WORKERS="4"
+
+# 日志配置
+export UNSTRUCTURED_LOG_LEVEL="INFO"
+export ENABLE_METRICS="true"
+```
+
+### Python 配置示例
+
+```python
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass
+class ETLConfig:
+    """完整的 ETL 配置类"""
+
+    # 云器 Lakehouse SQL 配置
+    clickzetta_service: str
+    clickzetta_username: str
+    clickzetta_password: str
+    clickzetta_workspace: str
+    clickzetta_schema: str
+    clickzetta_instance: str
+    clickzetta_vcluster: str
+
+    # DashScope 配置
+    dashscope_api_key: str
+    dashscope_model: str = "text-embedding-v3"
+
+    # 处理配置
+    sql_batch_size: int = 1000
+    volume_batch_size: int = 100
+    embed_batch_size: int = 25
+
+    # Volume 配置
+    default_volume_type: str = "named"
+    default_volume_name: Optional[str] = None
+
+    @classmethod
+    def from_env(cls) -> "ETLConfig":
+        """从环境变量创建配置"""
+        import os
+        return cls(
+            clickzetta_service=os.getenv("CLICKZETTA_SERVICE"),
+            clickzetta_username=os.getenv("CLICKZETTA_USERNAME"),
+            clickzetta_password=os.getenv("CLICKZETTA_PASSWORD"),
+            clickzetta_workspace=os.getenv("CLICKZETTA_WORKSPACE"),
+            clickzetta_schema=os.getenv("CLICKZETTA_SCHEMA"),
+            clickzetta_instance=os.getenv("CLICKZETTA_INSTANCE"),
+            clickzetta_vcluster=os.getenv("CLICKZETTA_VCLUSTER"),
+            dashscope_api_key=os.getenv("DASHSCOPE_API_KEY"),
+            dashscope_model=os.getenv("DASHSCOPE_MODEL", "text-embedding-v3"),
+        )
+```
+
+## 性能调优参数
+
+### 批处理大小建议
+
+```python
+# 不同场景的推荐批处理大小
+PERFORMANCE_CONFIGS = {
+    "small_dataset": {
+        "sql_batch_size": 500,
+        "volume_batch_size": 50,
+        "embed_batch_size": 10,
+    },
+    "medium_dataset": {
+        "sql_batch_size": 1000,
+        "volume_batch_size": 100,
+        "embed_batch_size": 25,
+    },
+    "large_dataset": {
+        "sql_batch_size": 5000,
+        "volume_batch_size": 500,
+        "embed_batch_size": 50,
+    },
+    "memory_constrained": {
+        "sql_batch_size": 100,
+        "volume_batch_size": 20,
+        "embed_batch_size": 5,
+    }
+}
+```
+
+### 连接池配置
+
+```python
+# 云器 Lakehouse 连接池配置
+POOL_CONFIG = {
+    "max_connections": 10,
+    "min_connections": 2,
+    "connection_timeout": 30,
+    "idle_timeout": 300,
+    "retry_attempts": 3,
+    "retry_delay": 1.0,
+}
+```
+
+## 测试工具
+
+### 连接测试
+
+```python
+def test_clickzetta_connection(config: ClickzettaConnectionConfig) -> bool:
+    """测试云器 Lakehouse 连接是否正常"""
+    try:
+        with config.get_session() as session:
+            result = session.sql("SELECT 1 as test").collect()
+            return len(result) == 1
+    except Exception:
+        return False
+
+def test_dashscope_connection(config: DashScopeEmbeddingConfig) -> bool:
+    """测试 DashScope 连接是否正常"""
+    try:
+        embeddings = config.embed_documents(["测试"])
+        return len(embeddings) == 1 and len(embeddings[0]) > 0
+    except Exception:
+        return False
+```
+
+### 数据验证工具
+
+```python
+def validate_etl_pipeline(
+    source_config: Dict,
+    destination_config: Dict,
+    sample_size: int = 100
+) -> Dict[str, bool]:
+    """验证完整的 ETL 管道"""
+    results = {
+        "source_connection": False,
+        "destination_connection": False,
+        "data_extraction": False,
+        "embedding_generation": False,
+        "data_upload": False
+    }
+
+    # 实现各项验证逻辑...
+
+    return results
+```
+
+