xparse-client 0.2.19__py3-none-any.whl → 0.3.0b3__py3-none-any.whl

example/1_basic_api_usage.py

@@ -0,0 +1,198 @@
+"""示例 1: 基础 API 使用
+
+演示 xparse-client 的基本 API 调用：
+- 单文件解析
+- 文档提取
+- Pipeline 执行
+
+运行方式:
+    export TEXTIN_APP_ID="your-app-id"
+    export TEXTIN_SECRET_CODE="your-secret-code"
+    python example/1_basic_api_usage.py
+"""
+
+import os
+from pathlib import Path
+
+from xparse_client import XParseClient
+from xparse_client.models import (
+    ChunkConfig,
+    ChunkStage,
+    EmbedConfig,
+    EmbedStage,
+    ExtractConfig,
+    ParseConfig,
+    ParseStage,
+)
+
+
+def example_1_parse_single_file():
+    """示例 1.1: 解析单个文件"""
+    print("\n" + "=" * 60)
+    print("示例 1.1: 解析单个文件")
+    print("=" * 60)
+
+    # 创建客户端
+    client = XParseClient.from_env()
+
+    # 创建测试文件
+    test_file = Path("test_document.txt")
+    test_file.write_text("这是一个测试文档。\n包含多行内容。")
+
+    try:
+        # 解析文档
+        with open(test_file, "rb") as f:
+            result = client.parse.partition(
+                file=f, filename=test_file.name, config=ParseConfig(provider="textin")
+            )
+
+        print("\n✅ 解析成功!")
+        print(f"  - 元素数量: {len(result.elements)}")
+        print(f"  - 记录 ID: {result.record_id}")
+
+        # 显示前 3 个元素
+        print("\n  前 3 个元素:")
+        for i, elem in enumerate(result.elements[:3], 1):
+            print(f"    {i}. [{elem.type}] {elem.text[:50]}...")
+
+    finally:
+        test_file.unlink(missing_ok=True)
+
+
+def example_2_extract_structured_data():
+    """示例 1.2: 提取结构化数据"""
+    print("\n" + "=" * 60)
+    print("示例 1.2: 提取结构化数据")
+    print("=" * 60)
+
+    client = XParseClient.from_env()
+
+    # 创建包含结构化信息的测试文件
+    test_file = Path("test_invoice.txt")
+    test_file.write_text("""
+    发票信息
+    --------
+    客户名称: 张三
+    金额: 1000 元
+    日期: 2026-01-27
+    """)
+
+    try:
+        # 定义提取 schema
+        schema = {
+            "type": "object",
+            "properties": {
+                "客户名称": {"type": "string", "description": "客户的名称"},
+                "金额": {"type": "number", "description": "发票金额（数字）"},
+                "日期": {"type": "string", "description": "发票日期"},
+            },
+            "required": [],
+        }
+
+        with open(test_file, "rb") as f:
+            result = client.extract.extract(
+                file=f, filename=test_file.name, extract_config=ExtractConfig(schema=schema)
+            )
+
+        print("\n✅ 提取成功!")
+        # Extract API 返回的数据在 extract_result.extracted_schema 中
+        if result.extract_result and "extracted_schema" in result.extract_result:
+            print(f"  提取的数据: {result.extract_result['extracted_schema']}")
+        else:
+            print("  未提取到数据")
+
+    finally:
+        test_file.unlink(missing_ok=True)
+
+
+def example_3_pipeline_execution():
+    """示例 1.3: Pipeline 完整流程"""
+    print("\n" + "=" * 60)
+    print("示例 1.3: Pipeline 完整流程 (parse → chunk → embed)")
+    print("=" * 60)
+
+    client = XParseClient.from_env()
+
+    # 创建测试文件
+    test_file = Path("test_long_doc.txt")
+    test_file.write_text("""
+    第一章 引言
+
+    本文档是一个测试文档，用于演示 xparse-client 的 Pipeline 功能。
+    Pipeline 可以将文档处理流程串联起来，包括解析、分块和向量化。
+
+    第二章 功能介绍
+
+    xparse-client 提供了统一的 API 入口，支持多种处理方式。
+    你可以根据需求选择合适的 API。
+
+    第三章 总结
+
+    希望这个示例对你有帮助！
+    """)
+
+    try:
+        # 定义处理阶段
+        stages = [
+            ParseStage(config=ParseConfig(provider="textin")),
+            ChunkStage(
+                config=ChunkConfig(
+                    strategy="by_title",  # 按标题分块
+                    max_characters=200,
+                    overlap=20,
+                )
+            ),
+            EmbedStage(config=EmbedConfig(provider="qwen", model_name="text-embedding-v3")),
+        ]
+
+        with open(test_file, "rb") as f:
+            result = client.pipeline.execute(file=f, filename=test_file.name, stages=stages)
+
+        print("\n✅ Pipeline 执行成功!")
+        print(f"  - 原始元素数: {result.stats.original_elements}")
+        print(f"  - 分块后元素数: {result.stats.chunked_elements}")
+        print(f"  - 向量化元素数: {result.stats.embedded_elements}")
+
+        # 显示第一个向量化的结果
+        if result.elements:
+            first_elem = result.elements[0]
+            print("\n  第一个分块:")
+            print(f"    - 文本: {first_elem.text[:100]}...")
+            print(f"    - 向量维度: {len(first_elem.embeddings) if first_elem.embeddings else 0}")
+
+    finally:
+        test_file.unlink(missing_ok=True)
+
+
+def main():
+    """主函数"""
+    print("\n" + "=" * 60)
+    print("xparse-client 基础 API 使用示例")
+    print("=" * 60)
+
+    # 检查环境变量
+    if not os.getenv("TEXTIN_APP_ID") or not os.getenv("TEXTIN_SECRET_CODE"):
+        print("\n❌ 错误: 请先设置环境变量:")
+        print("  export TEXTIN_APP_ID='your-app-id'")
+        print("  export TEXTIN_SECRET_CODE='your-secret-code'")
+        return
+
+    try:
+        # 运行示例
+        example_1_parse_single_file()
+        example_2_extract_structured_data()
+        example_3_pipeline_execution()
+
+        print("\n" + "=" * 60)
+        print("✅ 所有示例运行完成!")
+        print("=" * 60)
+
+    except Exception as e:
+        print(f"\n❌ 错误: {e}")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

example/2_async_job.py

@@ -0,0 +1,210 @@
+"""示例 2: 服务端异步任务
+
+演示如何使用服务端异步任务处理文档：
+- 创建异步任务
+- 轮询任务状态
+- 等待任务完成
+- 错误处理
+
+运行方式:
+    export TEXTIN_APP_ID="your-app-id"
+    export TEXTIN_SECRET_CODE="your-secret-code"
+    python example/2_async_job.py
+"""
+
+import os
+import time
+from pathlib import Path
+
+from xparse_client import XParseClient
+from xparse_client.models import ParseConfig
+
+
+def example_1_create_and_wait():
+    """示例 2.1: 创建异步任务并等待完成"""
+    print("\n" + "="*60)
+    print("示例 2.1: 创建异步任务并等待完成")
+    print("="*60)
+
+    client = XParseClient.from_env()
+
+    # 创建测试文件
+    test_file = Path("test_async.txt")
+    test_file.write_text("这是一个异步处理的测试文档。" * 100)
+
+    try:
+        # 创建异步任务
+        print("\n📤 创建异步任务...")
+        with open(test_file, "rb") as f:
+            job = client.parse.create_async_job(
+                file=f,
+                filename=test_file.name,
+                config=ParseConfig(provider="textin")
+            )
+
+        print("✅ 任务已创建:")
+        print(f"  - 任务 ID: {job.job_id}")
+
+        # 等待任务完成
+        print("\n⏳ 等待任务完成...")
+        result = client.parse.wait_for_result(
+            job_id=job.job_id,
+            timeout_seconds=60.0,
+            poll_interval_seconds=2.0
+        )
+
+        if result.is_completed:
+            print("\n✅ 任务完成!")
+            print(f"  - 任务 ID: {result.job_id}")
+            print(f"  - 文件 ID: {result.file_id}")
+            print(f"  - 结果 URL: {result.result_url}")
+            print("\n  💡 提示: 需要下载 result_url 来获取解析结果")
+        elif result.is_failed:
+            print(f"\n❌ 任务失败: {result.error_message}")
+        else:
+            print(f"\n⏸️  任务超时，当前状态: {result.status}")
+
+    finally:
+        test_file.unlink(missing_ok=True)
+
+
+def example_2_manual_polling():
+    """示例 2.2: 手动轮询任务状态"""
+    print("\n" + "="*60)
+    print("示例 2.2: 手动轮询任务状态")
+    print("="*60)
+
+    client = XParseClient.from_env()
+
+    # 创建测试文件
+    test_file = Path("test_manual_poll.txt")
+    test_file.write_text("手动轮询测试文档。" * 50)
+
+    try:
+        # 创建异步任务
+        with open(test_file, "rb") as f:
+            job = client.parse.create_async_job(
+                file=f,
+                filename=test_file.name,
+                config=ParseConfig(provider="textin")
+            )
+
+        print(f"✅ 任务已创建: {job.job_id}")
+
+        # 手动轮询
+        max_attempts = 30
+        poll_interval = 2.0
+
+        for attempt in range(max_attempts):
+            print(f"\n⏳ 第 {attempt + 1}/{max_attempts} 次检查...")
+
+            # 查询任务状态
+            status = client.parse.get_result(job_id=job.job_id)
+
+            if status.is_completed:
+                print("\n✅ 任务完成!")
+                print(f"  - 耗时: ~{(attempt + 1) * poll_interval} 秒")
+                print(f"  - 结果 URL: {status.result_url}")
+                break
+
+            elif status.is_failed:
+                print(f"\n❌ 任务失败: {status.error_message}")
+                break
+
+            elif status.status == "scheduled":
+                print("  状态: 队列中...")
+                time.sleep(poll_interval)
+
+            elif status.status == "in_progress":
+                print("  状态: 处理中...")
+                time.sleep(poll_interval)
+
+        else:
+            print(f"\n⏸️  超时: 任务未在 {max_attempts * poll_interval} 秒内完成")
+
+    finally:
+        test_file.unlink(missing_ok=True)
+
+
+def example_3_error_handling():
+    """示例 2.3: 异步任务错误处理"""
+    print("\n" + "="*60)
+    print("示例 2.3: 异步任务错误处理")
+    print("="*60)
+
+    client = XParseClient.from_env()
+
+    # 创建一个正常的任务，演示如何处理超时
+    test_file = Path("test_timeout.txt")
+    test_file.write_text("测试超时处理")
+
+    try:
+        print("\n📤 创建任务并设置很短的超时时间...")
+        with open(test_file, "rb") as f:
+            job = client.parse.create_async_job(
+                file=f,
+                filename=test_file.name,
+                config=ParseConfig(provider="textin")
+            )
+
+        print(f"✅ 任务已创建: {job.job_id}")
+
+        # 设置一个很短的超时时间来演示超时处理
+        try:
+            result = client.parse.wait_for_result(
+                job_id=job.job_id,
+                timeout_seconds=0.5,  # 很短的超时
+                poll_interval_seconds=0.2
+            )
+
+            if result.is_completed:
+                print("\n✅ 任务很快完成了!")
+            elif result.is_failed:
+                print("\n❌ 任务失败:")
+                print(f"  - 错误信息: {result.error_message}")
+
+        except Exception as e:
+            print(f"\n⏸️  捕获到超时异常: {type(e).__name__}")
+            print(f"  这是正常的，演示了如何处理超时情况")
+
+    finally:
+        test_file.unlink(missing_ok=True)
+
+
+def main():
+    """主函数"""
+    print("\n" + "="*60)
+    print("xparse-client 服务端异步任务示例")
+    print("="*60)
+
+    # 检查环境变量
+    if not os.getenv("TEXTIN_APP_ID") or not os.getenv("TEXTIN_SECRET_CODE"):
+        print("\n❌ 错误: 请先设置环境变量:")
+        print("  export TEXTIN_APP_ID='your-app-id'")
+        print("  export TEXTIN_SECRET_CODE='your-secret-code'")
+        return
+
+    print("\n💡 提示:")
+    print("  - 异步任务适合处理大文件或耗时操作")
+    print("  - 创建任务后立即返回，不会阻塞")
+    print("  - 可以使用 wait_for_result() 自动等待")
+    print("  - 也可以手动轮询 get_result() 检查状态")
+
+    try:
+        # 运行示例
+        example_1_create_and_wait()
+        example_2_manual_polling()
+        example_3_error_handling()
+
+        print("\n" + "="*60)
+        print("✅ 所有示例运行完成!")
+        print("="*60)
+
+    except Exception as e:
+        print(f"\n❌ 错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

example/3_local_workflow.py

@@ -0,0 +1,300 @@
+"""示例 3: 本地批量处理工作流
+
+演示本地批量处理的完整流程：
+- 从本地目录读取文件
+- 批量调用 Pipeline API
+- 写入本地或向量数据库
+- 查看处理统计
+
+运行方式:
+    export TEXTIN_APP_ID="your-app-id"
+    export TEXTIN_SECRET_CODE="your-secret-code"
+    python example/3_local_workflow.py
+"""
+
+import os
+from pathlib import Path
+
+from xparse_client import XParseClient
+from xparse_client.connectors import LocalDestination, LocalSource
+from xparse_client.models import (
+    ChunkConfig,
+    ChunkStage,
+    EmbedConfig,
+    EmbedStage,
+    ParseConfig,
+    ParseStage,
+)
+
+
+def example_1_basic_workflow():
+    """示例 3.1: 基础本地批量处理"""
+    print("\n" + "="*60)
+    print("示例 3.1: 基础本地批量处理")
+    print("="*60)
+
+    client = XParseClient.from_env()
+
+    # 准备测试目录和文件
+    source_dir = Path("./test_docs")
+    output_dir = Path("./test_output")
+    source_dir.mkdir(exist_ok=True)
+    output_dir.mkdir(exist_ok=True)
+
+    # 创建多个测试文件
+    for i in range(3):
+        (source_dir / f"doc_{i+1}.txt").write_text(
+            f"这是第 {i+1} 个测试文档。\n" * 10
+        )
+
+    try:
+        print(f"\n📁 源目录: {source_dir}")
+        print(f"📁 输出目录: {output_dir}")
+
+        # 定义处理阶段
+        stages = [
+            ParseStage(config=ParseConfig(provider="textin")),
+            ChunkStage(config=ChunkConfig(
+                strategy="basic",
+                max_characters=500
+            )),
+            EmbedStage(config=EmbedConfig(provider="qwen"))
+        ]
+
+        # 执行工作流
+        print("\n⏳ 开始处理...")
+        result = client.local.run_workflow(
+            source=LocalSource(directory=str(source_dir), pattern=["*.txt"]),
+            destination=LocalDestination(output_dir=str(output_dir)),
+            stages=stages
+        )
+
+        # 显示结果
+        print("\n✅ 处理完成!")
+        print(f"  - 总文件数: {result.total}")
+        print(f"  - 成功: {result.success}")
+        print(f"  - 失败: {result.failed}")
+        print(f"  - 耗时: {result.duration:.2f} 秒")
+
+        # 列出输出文件
+        output_files = list(output_dir.glob("*.json"))
+        print(f"\n📄 输出文件 ({len(output_files)} 个):")
+        for f in output_files:
+            print(f"  - {f.name}")
+
+    finally:
+        # 清理测试文件
+        import shutil
+        if source_dir.exists():
+            shutil.rmtree(source_dir)
+        if output_dir.exists():
+            shutil.rmtree(output_dir)
+
+
+def example_2_with_progress():
+    """示例 3.2: 带进度回调的批量处理"""
+    print("\n" + "="*60)
+    print("示例 3.2: 带进度回调的批量处理")
+    print("="*60)
+
+    client = XParseClient.from_env()
+
+    # 准备测试目录和文件
+    source_dir = Path("./test_docs_progress")
+    output_dir = Path("./test_output_progress")
+    source_dir.mkdir(exist_ok=True)
+    output_dir.mkdir(exist_ok=True)
+
+    # 创建 5 个测试文件
+    for i in range(5):
+        (source_dir / f"document_{i+1}.txt").write_text(
+            f"文档 {i+1} 的内容。\n" * 20
+        )
+
+    try:
+        # 定义进度回调
+        def on_progress(current, total, message):
+            percentage = (current / total) * 100
+            print(f"  [{current}/{total}] {percentage:.1f}% - {message}")
+
+        print(f"\n⏳ 开始处理 {len(list(source_dir.glob('*.txt')))} 个文件...")
+
+        stages = [
+            ParseStage(config=ParseConfig(provider="textin")),
+            EmbedStage(config=EmbedConfig(provider="qwen"))
+        ]
+
+        result = client.local.run_workflow(
+            source=LocalSource(directory=str(source_dir)),
+            destination=LocalDestination(output_dir=str(output_dir)),
+            stages=stages,
+            progress_callback=on_progress  # 添加进度回调
+        )
+
+        print("\n✅ 全部完成!")
+        print(f"  成功率: {result.success}/{result.total} ({result.success/result.total*100:.1f}%)")
+
+    finally:
+        # 清理
+        import shutil
+        if source_dir.exists():
+            shutil.rmtree(source_dir)
+        if output_dir.exists():
+            shutil.rmtree(output_dir)
+
+
+def example_3_error_handling():
+    """示例 3.3: 错误处理策略"""
+    print("\n" + "="*60)
+    print("示例 3.3: 错误处理策略")
+    print("="*60)
+
+    client = XParseClient.from_env()
+
+    # 准备测试目录
+    source_dir = Path("./test_docs_errors")
+    output_dir = Path("./test_output_errors")
+    source_dir.mkdir(exist_ok=True)
+    output_dir.mkdir(exist_ok=True)
+
+    # 创建正常文件和可能出错的文件
+    (source_dir / "good_1.txt").write_text("正常文档 1")
+    (source_dir / "good_2.txt").write_text("正常文档 2")
+    (source_dir / "empty.txt").write_text("")  # 空文件可能导致错误
+
+    try:
+        print("\n📋 错误处理策略: continue (遇到错误继续处理)")
+
+        stages = [
+            ParseStage(config=ParseConfig(provider="textin")),
+        ]
+
+        result = client.local.run_workflow(
+            source=LocalSource(directory=str(source_dir)),
+            destination=LocalDestination(output_dir=str(output_dir)),
+            stages=stages,
+            on_error="continue",  # 遇到错误继续处理
+            max_retries=2         # 失败重试 2 次
+        )
+
+        print("\n✅ 处理完成!")
+        print(f"  - 成功: {result.success}")
+        print(f"  - 失败: {result.failed}")
+
+        if result.failed_files:
+            print("\n❌ 失败的文件:")
+            for failed in result.failed_files:
+                print(f"  - {failed.file_path}: {failed.error}")
+
+    finally:
+        # 清理
+        import shutil
+        if source_dir.exists():
+            shutil.rmtree(source_dir)
+        if output_dir.exists():
+            shutil.rmtree(output_dir)
+
+
+def example_4_milvus_workflow():
+    """示例 3.4: 写入 Milvus 向量数据库"""
+    print("\n" + "="*60)
+    print("示例 3.4: 写入 Milvus 向量数据库")
+    print("="*60)
+
+    print("\n💡 提示: 此示例需要安装 Milvus 依赖")
+    print("  pip install xparse-client[milvus]")
+
+    try:
+        from xparse_client.connectors import MilvusDestination
+    except ImportError:
+        print("\n⚠️  跳过此示例: 未安装 pymilvus")
+        return
+
+    client = XParseClient.from_env()
+
+    # 准备测试目录
+    source_dir = Path("./test_docs_milvus")
+    source_dir.mkdir(exist_ok=True)
+
+    # 创建测试文件
+    for i in range(3):
+        (source_dir / f"vector_doc_{i+1}.txt").write_text(
+            f"向量数据库测试文档 {i+1}。\n" * 15
+        )
+
+    try:
+        print("\n📊 目标: Milvus 向量数据库")
+
+        stages = [
+            ParseStage(config=ParseConfig(provider="textin")),
+            ChunkStage(config=ChunkConfig(
+                strategy="by_title",
+                max_characters=300
+            )),
+            EmbedStage(config=EmbedConfig(provider="qwen"))
+        ]
+
+        result = client.local.run_workflow(
+            source=LocalSource(directory=str(source_dir)),
+            destination=MilvusDestination(
+                db_path="./demo_vectors.db",  # 本地 Milvus
+                collection_name="demo_collection",
+                dimension=1024  # qwen 向量维度
+            ),
+            stages=stages
+        )
+
+        print("\n✅ 向量已写入 Milvus!")
+        print("  - Collection: demo_collection")
+        print(f"  - 向量数量: {result.success} 个文档的向量")
+
+        # 清理 Milvus 文件
+        if Path("demo_vectors.db").exists():
+            import shutil
+            shutil.rmtree("demo_vectors.db")
+
+    finally:
+        # 清理
+        import shutil
+        if source_dir.exists():
+            shutil.rmtree(source_dir)
+
+
+def main():
+    """主函数"""
+    print("\n" + "="*60)
+    print("xparse-client 本地批量处理工作流示例")
+    print("="*60)
+
+    # 检查环境变量
+    if not os.getenv("TEXTIN_APP_ID") or not os.getenv("TEXTIN_SECRET_CODE"):
+        print("\n❌ 错误: 请先设置环境变量:")
+        print("  export TEXTIN_APP_ID='your-app-id'")
+        print("  export TEXTIN_SECRET_CODE='your-secret-code'")
+        return
+
+    print("\n💡 提示:")
+    print("  - 本地批量处理会在你的机器上同步执行")
+    print("  - 适合中小规模的批量导入任务")
+    print("  - 支持进度回调和错误处理")
+    print("  - 可以写入本地文件或向量数据库")
+
+    try:
+        # 运行示例
+        example_1_basic_workflow()
+        example_2_with_progress()
+        example_3_error_handling()
+        example_4_milvus_workflow()
+
+        print("\n" + "="*60)
+        print("✅ 所有示例运行完成!")
+        print("="*60)
+
+    except Exception as e:
+        print(f"\n❌ 错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()