xparse-client 0.2.7__tar.gz → 0.2.8__tar.gz

{xparse_client-0.2.7 → xparse_client-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xparse-client
-Version: 0.2.7
+Version: 0.2.8
 Summary: 面向Agent和RAG的新一代文档处理 AI Infra
 License-Expression: MIT
 Project-URL: Homepage, https://gitlab.intsig.net/xparse1/xparse-pipeline
@@ -517,298 +517,357 @@ Parse 参数中有必填项`Provider`，表示文档解析服务的供应商，
 
 ## 💡 使用示例
 
-### 示例 1: 使用 config 字典配置（推荐）
+### 示例 1: 手动创建 Pipeline（推荐）
 
 ```python
-from xparse_client import create_pipeline_from_config
+from xparse_client import (
+    Pipeline, S3Source, MilvusDestination,
+    ParseConfig, ChunkConfig, EmbedConfig, Stage
+)
 
-# 完整的配置示例
-config = {
-    # S3 数据源配置
-    'source': {
-        'type': 's3',
-        'endpoint': 'https://your-minio.com',
-        'access_key': 'your-access-key',
-        'secret_key': 'your-secret-key',
-        'bucket': 'documents',
-        'prefix': 'pdfs/',
-        'region': 'us-east-1',
-        'pattern': '*.pdf'  # 仅处理匹配的文件
-    },
-    
-    # Milvus 目的地配置
-    'destination': {
-        'type': 'milvus',
-        'db_path': './vectors.db',
-        'collection_name': 'documents',
-        'dimension': 1024
-    },
-    
-    # API 配置
-    'api_base_url': 'https://api.textin.com/api/xparse',
-    'api_headers': {
+# 创建数据源
+source = S3Source(
+    endpoint='https://your-minio.com',
+    access_key='your-access-key',
+    secret_key='your-secret-key',
+    bucket='documents',
+    prefix='pdfs/',
+    region='us-east-1',
+    pattern='*.pdf',  # 仅处理匹配的文件
+    recursive=False   # 不递归子目录
+)
+
+# 创建目的地
+destination = MilvusDestination(
+    db_path='./vectors.db',
+    collection_name='documents',
+    dimension=1024
+)
+
+# 配置处理阶段
+stages = [
+    Stage(
+        type='parse',
+        config=ParseConfig(provider='textin')
+    ),
+    Stage(
+        type='chunk',
+        config=ChunkConfig(
+            strategy='by_title',           # 按标题分块
+            include_orig_elements=False,
+            new_after_n_chars=512,
+            max_characters=1024,
+            overlap=50                     # 块之间重叠 50 字符
+        )
+    ),
+    Stage(
+        type='embed',
+        config=EmbedConfig(
+            provider='qwen',
+            model_name='text-embedding-v3'
+        )
+    )
+]
+
+# 创建并运行 Pipeline
+pipeline = Pipeline(
+    source=source,
+    destination=destination,
+    api_base_url='https://api.textin.com/api/xparse',
+    api_headers={
         'x-ti-app-id': 'your-app-id',
         'x-ti-secret-code': 'your-secret-code'
     },
-    
-    # Stages 配置
-    'stages': [
-        {
-            'type': 'parse',
-            'config': {
-                'provider': 'textin'
-            }
-        },
-        {
-            'type': 'chunk',
-            'config': {
-                'strategy': 'by_title',           # 按标题分块
-                'include_orig_elements': False,
-                'new_after_n_chars': 512,
-                'max_characters': 1024,
-                'overlap': 50                    # 块之间重叠 50 字符
-            }
-        },
-        {
-            'type': 'embed',
-            'config': {
-                'provider': 'qwen',
-                'model_name': 'text-embedding-v3'
-            }
-        }
-    ]
-}
+    stages=stages
+)
 
-# 使用配置创建并运行 pipeline
-pipeline = create_pipeline_from_config(config)
 pipeline.run()
 ```
 
-### 示例 2: 本地到本地（测试）
+### 示例 1.1: 输出配置字典
+
+手动创建 Pipeline 后，可以使用 `get_config()` 方法获取配置字典：
 
 ```python
-from datetime import datetime, timezone
-from xparse_client import create_pipeline_from_config
+from xparse_client import (
+    Pipeline, LocalSource, LocalDestination,
+    ParseConfig, ChunkConfig, EmbedConfig, Stage
+)
 
-config = {
-    'source': {
-        'type': 'local',
-        'directory': './test_files',
-        'pattern': '*.pdf'
-    },
-    'destination': {
-        'type': 'local',
-        'output_dir': './test_output'
+# 手动创建 Pipeline
+source = LocalSource(
+    directory='./test_files',
+    pattern='*.pdf',
+    recursive=False
+)
+
+destination = LocalDestination(output_dir='./test_output')
+
+stages = [
+    Stage(type='parse', config=ParseConfig(provider='textin')),
+    Stage(type='chunk', config=ChunkConfig(strategy='basic', max_characters=1024)),
+    Stage(type='embed', config=EmbedConfig(provider='qwen', model_name='text-embedding-v3'))
+]
+
+pipeline = Pipeline(
+    source=source,
+    destination=destination,
+    api_base_url='https://api.textin.com/api/xparse',
+    api_headers={
+        'x-ti-app-id': 'your-app-id',
+        'x-ti-secret-code': 'your-secret-code'
     },
-    'api_base_url': 'https://api.textin.com/api/xparse',
-    'api_headers': {
+    stages=stages
+)
+
+# 获取配置字典（格式与 create_pipeline_from_config 的入参一致）
+config_dict = pipeline.get_config()
+
+# 可以保存为 JSON 文件
+import json
+with open('pipeline_config.json', 'w', encoding='utf-8') as f:
+    json.dump(config_dict, f, indent=2, ensure_ascii=False)
+
+# 或者用于创建新的 Pipeline（需要补充敏感信息如 access_key, secret_key 等）
+# from xparse_client import create_pipeline_from_config
+# new_pipeline = create_pipeline_from_config(config_dict)
+```
+
+### 示例 2: 本地到本地（测试）
+
+```python
+from xparse_client import (
+    Pipeline, LocalSource, LocalDestination,
+    ParseConfig, ChunkConfig, EmbedConfig, Stage
+)
+
+# 创建本地数据源
+source = LocalSource(
+    directory='./test_files',
+    pattern='*.pdf',
+    recursive=False
+)
+
+# 创建本地输出目的地
+destination = LocalDestination(output_dir='./test_output')
+
+# 配置处理阶段
+stages = [
+    Stage(
+        type='parse',
+        config=ParseConfig(provider='textin')
+    ),
+    Stage(
+        type='chunk',
+        config=ChunkConfig(
+            strategy='basic',
+            max_characters=1024
+        )
+    ),
+    Stage(
+        type='embed',
+        config=EmbedConfig(
+            provider='qwen',
+            model_name='text-embedding-v3'
+        )
+    )
+]
+
+# 创建并运行 Pipeline
+pipeline = Pipeline(
+    source=source,
+    destination=destination,
+    api_base_url='https://api.textin.com/api/xparse',
+    api_headers={
         'x-ti-app-id': 'your-app-id',
         'x-ti-secret-code': 'your-secret-code'
     },
-    # Stages 配置
-    'stages': [
-        {
-            'type': 'parse',
-            'config': {
-                'provider': 'textin'
-            }
-        },
-        {
-            'type': 'chunk',
-            'config': {
-                'strategy': 'basic',
-                'max_characters': 1024
-            }
-        },
-        {
-            'type': 'embed',
-            'config': {
-                'provider': 'qwen',
-                'model_name': 'text-embedding-v3'
-            }
-        }
-    ]
-}
+    stages=stages
+)
 
-pipeline = create_pipeline_from_config(config)
 pipeline.run()
 ```
 
 ### 示例 3: 不同分块策略的配置
 
 ```python
-from xparse_client import create_pipeline_from_config
+from xparse_client import (
+    Pipeline, S3Source, MilvusDestination,
+    ParseConfig, ChunkConfig, EmbedConfig, Stage
+)
+
+# 创建数据源和目的地
+source = S3Source(...)
+destination = MilvusDestination(...)
 
 # 配置 1：按页面分块（适合 PDF 文档）
-config_by_page = {
-    'source': {...},
-    'destination': {...},
-    'api_base_url': 'https://api.textin.com/api/xparse',
-    'api_headers': {...},
-    'stages': [
-        {
-            'type': 'parse',
-            'config': {
-                'provider': 'textin'
-            }
-        },
-        {
-            'type': 'chunk',
-            'config': {
-                'strategy': 'by_page',         # 按页面分块
-                'max_characters': 2048,       # 增大块大小
-                'overlap': 100                # 页面间重叠 100 字符
-            }
-        },
-        {
-            'type': 'embed',
-            'config': {
-                'provider': 'qwen',
-                'model_name': 'text-embedding-v4'  # 使用更高精度的模型
-            }
-        }
-    ]
-}
+stages_by_page = [
+    Stage(
+        type='parse',
+        config=ParseConfig(provider='textin')
+    ),
+    Stage(
+        type='chunk',
+        config=ChunkConfig(
+            strategy='by_page',         # 按页面分块
+            max_characters=2048,         # 增大块大小
+            overlap=100                  # 页面间重叠 100 字符
+        )
+    ),
+    Stage(
+        type='embed',
+        config=EmbedConfig(
+            provider='qwen',
+            model_name='text-embedding-v4'  # 使用更高精度的模型
+        )
+    )
+]
 
 # 配置 2：按标题分块（适合结构化文档）
-config_by_title = {
-    'source': {...},
-    'destination': {...},
-    'api_base_url': 'https://api.textin.com/api/xparse',
-    'api_headers': {...},
-    'stages': [
-        {
-            'type': 'parse',
-            'config': {
-                'provider': 'textin'
-            }
-        },
-        {
-            'type': 'chunk',
-            'config': {
-                'strategy': 'by_title',        # 按标题分块
-                'include_orig_elements': True, # 保留原始元素信息
-                'max_characters': 1536
-            }
-        },
-        {
-            'type': 'embed',
-            'config': {
-                'provider': 'qwen',
-                'model_name': 'text-embedding-v3'
-            }
-        }
-    ]
-}
+stages_by_title = [
+    Stage(
+        type='parse',
+        config=ParseConfig(provider='textin')
+    ),
+    Stage(
+        type='chunk',
+        config=ChunkConfig(
+            strategy='by_title',        # 按标题分块
+            include_orig_elements=True,  # 保留原始元素信息
+            max_characters=1536
+        )
+    ),
+    Stage(
+        type='embed',
+        config=EmbedConfig(
+            provider='qwen',
+            model_name='text-embedding-v3'
+        )
+    )
+]
 
 # 根据文档类型选择配置
-pipeline = create_pipeline_from_config(config_by_page)
+pipeline = Pipeline(
+    source=source,
+    destination=destination,
+    api_base_url='https://api.textin.com/api/xparse',
+    api_headers={...},
+    stages=stages_by_page  # 或 stages_by_title
+)
 pipeline.run()
 ```
 
 ### 示例 4: FTP 数据源配置
 
 ```python
-from xparse_client import create_pipeline_from_config
+from xparse_client import (
+    Pipeline, FtpSource, MilvusDestination,
+    ParseConfig, ChunkConfig, EmbedConfig, Stage
+)
 
-config = {
-    # FTP 数据源
-    'source': {
-        'type': 'ftp',
-        'host': 'ftp.example.com',
-        'port': 21,
-        'username': 'user',
-        'password': 'pass'
-    },
-    
-    # Milvus 目的地
-    'destination': {
-        'type': 'milvus',
-        'db_path': './vectors.db',
-        'collection_name': 'ftp_docs',
-        'dimension': 1024
-    },
-    
-    'api_base_url': 'https://api.textin.com/api/xparse',
-    'api_headers': {
+# 创建 FTP 数据源
+source = FtpSource(
+    host='ftp.example.com',
+    port=21,
+    username='user',
+    password='pass',
+    pattern='*.pdf',
+    recursive=False
+)
+
+# 创建 Milvus 目的地
+destination = MilvusDestination(
+    db_path='./vectors.db',
+    collection_name='ftp_docs',
+    dimension=1024
+)
+
+# 配置处理阶段
+stages = [
+    Stage(
+        type='parse',
+        config=ParseConfig(provider='textin')
+    ),
+    Stage(
+        type='chunk',
+        config=ChunkConfig(
+            strategy='basic',
+            max_characters=1024
+        )
+    ),
+    Stage(
+        type='embed',
+        config=EmbedConfig(
+            provider='qwen',
+            model_name='text-embedding-v3'
+        )
+    )
+]
+
+# 创建并运行 Pipeline
+pipeline = Pipeline(
+    source=source,
+    destination=destination,
+    api_base_url='https://api.textin.com/api/xparse',
+    api_headers={
         'x-ti-app-id': 'app-id',
         'x-ti-secret-code': 'secret'
     },
-    
-    # Stages 配置
-    'stages': [
-        {
-            'type': 'parse',
-            'config': {
-                'provider': 'textin'
-            }
-        },
-        {
-            'type': 'chunk',
-            'config': {
-                'strategy': 'basic',
-                'max_characters': 1024
-            }
-        },
-        {
-            'type': 'embed',
-            'config': {
-                'provider': 'qwen',
-                'model_name': 'text-embedding-v3'
-            }
-        }
-    ]
-}
+    stages=stages
+)
 
-pipeline = create_pipeline_from_config(config)
 pipeline.run()
 ```
 
 ### 示例 5: 获取处理统计信息
 
 ```python
-from xparse_client import create_pipeline_from_config
+from datetime import datetime, timezone
+from xparse_client import (
+    Pipeline, LocalSource, LocalDestination,
+    ParseConfig, ChunkConfig, EmbedConfig, Stage
+)
 
-config = {
-    'source': {
-        'type': 'local',
-        'directory': './docs',
-        'pattern': '*.pdf'
-    },
-    'destination': {
-        'type': 'local',
-        'output_dir': './output'
-    },
-    'api_base_url': 'https://api.textin.com/api/xparse',
-    'api_headers': {
+# 创建 Pipeline
+source = LocalSource(
+    directory='./docs',
+    pattern='*.pdf',
+    recursive=False
+)
+
+destination = LocalDestination(output_dir='./output')
+
+stages = [
+    Stage(
+        type='parse',
+        config=ParseConfig(provider='textin')
+    ),
+    Stage(
+        type='chunk',
+        config=ChunkConfig(
+            strategy='basic',
+            max_characters=1024
+        )
+    ),
+    Stage(
+        type='embed',
+        config=EmbedConfig(
+            provider='qwen',
+            model_name='text-embedding-v3'
+        )
+    )
+]
+
+pipeline = Pipeline(
+    source=source,
+    destination=destination,
+    api_base_url='https://api.textin.com/api/xparse',
+    api_headers={
         'x-ti-app-id': 'your-app-id',
         'x-ti-secret-code': 'your-secret-code'
     },
-    'stages': [
-        {
-            'type': 'parse',
-            'config': {
-                'provider': 'textin'
-            }
-        },
-        {
-            'type': 'chunk',
-            'config': {
-                'strategy': 'basic',
-                'max_characters': 1024
-            }
-        },
-        {
-            'type': 'embed',
-            'config': {
-                'provider': 'qwen',
-                'model_name': 'text-embedding-v3'
-            }
-        }
-    ]
-}
-
-pipeline = create_pipeline_from_config(config)
+    stages=stages
+)
 
 # 处理单个文件并获取统计信息
 file_bytes, data_source = pipeline.source.read_file('document.pdf')