vectorvein 0.3.16__tar.gz → 0.3.18__tar.gz

vectorvein-0.3.18/PKG-INFO

@@ -0,0 +1,716 @@
+Metadata-Version: 2.1
+Name: vectorvein
+Version: 0.3.18
+Summary: VectorVein Python SDK
+Author-Email: Anderson <andersonby@163.com>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.99.3
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: anthropic>=0.47.1
+Requires-Dist: pydantic>=2.8.2
+Requires-Dist: Pillow>=10.4.0
+Requires-Dist: deepseek-tokenizer>=0.1.0
+Requires-Dist: qwen-tokenizer>=0.2.0
+Requires-Dist: pycryptodome>=3.21.0
+Provides-Extra: server
+Requires-Dist: fastapi; extra == "server"
+Requires-Dist: uvicorn; extra == "server"
+Provides-Extra: redis
+Requires-Dist: redis; extra == "redis"
+Provides-Extra: diskcache
+Requires-Dist: diskcache; extra == "diskcache"
+Provides-Extra: vertex
+Requires-Dist: google-auth>=2.35.0; extra == "vertex"
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.28.57; extra == "bedrock"
+Requires-Dist: botocore>=1.31.57; extra == "bedrock"
+Description-Content-Type: text/markdown
+
+# VectorVein Python SDK
+
+[![PyPI version](https://badge.fury.io/py/vectorvein.svg)](https://badge.fury.io/py/vectorvein)
+[![Python versions](https://img.shields.io/pypi/pyversions/vectorvein.svg)](https://pypi.org/project/vectorvein/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+VectorVein Python SDK 是一个功能强大的 Python 库，提供了对向量脉络(VectorVein)平台的完整访问能力。它包含两大核心功能：
+1. **向量脉络 API 客户端** - 用于调用向量脉络的工作流和VApp功能
+2. **多模型聊天客户端** - 统一的接口支持多种大语言模型（Claude、OpenAI、通义千问、智谱AI等）
+3. **工作流设计框架** - 用于构建和设计复杂的AI工作流
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+pip install vectorvein
+```
+
+### 基本使用
+
+#### 1. VectorVein API 客户端
+
+```python
+from vectorvein.api import VectorVeinClient, WorkflowInputField
+
+# 创建客户端实例
+client = VectorVeinClient(api_key="YOUR_API_KEY")
+
+# 准备工作流输入字段
+input_fields = [
+    WorkflowInputField(
+        node_id="8fc6eceb-8599-46a7-87fe-58bf7c0b633e",
+        field_name="商品名称",
+        value="测试商品"
+    )
+]
+
+# 异步运行工作流
+rid = client.run_workflow(
+    wid="abcde0985736457aa72cc667f17bfc89",
+    input_fields=input_fields,
+    wait_for_completion=False
+)
+print(f"工作流运行ID: {rid}")
+
+# 同步运行工作流
+result = client.run_workflow(
+    wid="abcde0985736457aa72cc667f17bfc89",
+    input_fields=input_fields,
+    wait_for_completion=True
+)
+print(f"工作流运行结果: {result}")
+```
+
+#### 2. 聊天客户端
+
+```python
+from vectorvein.chat_clients import create_chat_client, BackendType
+from vectorvein.settings import settings
+
+# 加载设置（包含API密钥等配置）
+settings.load({
+    "rate_limit": {
+        "enabled": True,
+        "backend": "redis",  # 或 "diskcache"
+        "redis": {
+            "host": "127.0.0.1",
+            "port": 6379,
+            "db": 0,
+        },
+        "default_rpm": 60,
+        "default_tpm": 1000000,
+    },
+    "endpoints": [
+        {
+            "id": "anthropic-default",
+            "api_base": "https://api.anthropic.com",
+            "api_key": "your_claude_api_key",
+            "rpm": 60,
+            "tpm": 1000000
+        },
+        {
+            "id": "openai-default", 
+            "api_base": "https://api.openai.com/v1",
+            "api_key": "your_openai_api_key",
+            "rpm": 3500,
+            "tpm": 90000
+        }
+    ],
+    "anthropic": {
+        "models": {
+            "claude-3-7-sonnet-20250219": {
+                "id": "claude-3-7-sonnet-20250219",
+                "endpoints": ["anthropic-default"],
+                "context_length": 200000,
+                "max_output_tokens": 8192,
+                "function_call_available": True,
+                "native_multimodal": True
+            }
+        }
+    },
+    "openai": {
+        "models": {
+            "gpt-4o": {
+                "id": "gpt-4o", 
+                "endpoints": ["openai-default"],
+                "context_length": 128000,
+                "max_output_tokens": 16384,
+                "function_call_available": True,
+                "response_format_available": True,
+                "native_multimodal": True
+            }
+        }
+    }
+})
+
+# 创建 Claude 客户端
+client = create_chat_client(BackendType.Anthropic, model="claude-3-7-sonnet-20250219")
+
+# 发送消息
+response = client.create_completion([
+    {"role": "user", "content": "你好，请介绍一下人工智能的发展历程"}
+])
+print(response.content)
+
+# 创建 OpenAI 客户端
+openai_client = create_chat_client(BackendType.OpenAI, model="gpt-4o")
+
+# 流式响应
+for chunk in openai_client.create_stream([
+    {"role": "user", "content": "写一首关于春天的诗"}
+]):
+    print(chunk.content, end="", flush=True)
+```
+
+#### 3. 工作流设计
+
+```python
+from vectorvein.workflow.graph.workflow import Workflow
+from vectorvein.workflow.nodes.llms import Claude
+from vectorvein.workflow.nodes.text_processing import TemplateCompose
+from vectorvein.workflow.nodes.output import Text
+
+# 创建工作流
+workflow = Workflow()
+
+# 创建节点
+template = TemplateCompose()
+template.add_port(name="用户输入", port_type="textarea", show=True)
+template.ports["template"].value = "请回答以下问题：{{用户输入}}"
+
+claude = Claude()
+claude.ports["llm_model"].value = "claude-3-7-sonnet-20250219"
+claude.ports["temperature"].value = 0.7
+
+output = Text()
+output.ports["output_title"].value = "AI回答"
+
+# 添加节点到工作流
+workflow.add_nodes([template, claude, output])
+
+# 连接节点
+workflow.connect(template, "output", claude, "prompt")
+workflow.connect(claude, "output", output, "text")
+
+# 布局和导出
+workflow.layout()
+print(workflow.to_json())
+```
+
+## 📚 功能特性
+
+### VectorVein API 客户端
+
+- **工作流管理**: 运行工作流、检查状态、管理执行
+- **访问密钥管理**: 创建、获取、列表、更新、删除访问密钥
+- **VApp 集成**: 生成VApp访问链接
+- **异步支持**: 完整的异步API支持
+- **错误处理**: 详细的异常类型和错误信息
+
+### 聊天客户端
+
+#### 支持的模型提供商
+
+- **Anthropic**: Claude-3, Claude-3.5, Claude-4, Claude Opus 等
+- **OpenAI**: GPT-3.5, GPT-4, GPT-4o, o1, o3 系列
+- **阿里云**: 通义千问 Qwen2.5, Qwen3, QVQ 等
+- **智谱AI**: GLM-4, GLM-4.5, GLM-Z1 等
+- **DeepSeek**: DeepSeek-Chat, DeepSeek-Reasoner
+- **月之暗面**: Kimi, Moonshot 系列
+- **Google**: Gemini 1.5, Gemini 2.0, Gemini 2.5
+- **百川智能**: Baichuan3, Baichuan4
+- **零一万物**: Yi-Lightning, Yi-Vision
+- **MiniMax**: MiniMax-Text, MiniMax-M1
+- **Mistral**: Mistral Large, Codestral
+- **Groq**: Llama3, Mixtral 等
+- **XAI**: Grok-2, Grok-3, Grok-4
+- **百度文心**: ERNIE 系列
+- **阶跃星辰**: Step-1, Step-2 系列
+- **本地模型**: 支持本地部署的模型
+
+#### 核心功能
+
+- **统一接口**: 所有模型使用相同的API接口
+- **流式响应**: 支持实时流式输出
+- **多模态**: 支持图像、音频输入的模型
+- **工具调用**: 支持Function Calling的模型
+- **上下文管理**: 自动处理上下文长度限制
+- **令牌统计**: 精确的令牌计数和使用统计
+- **速率限制**: 内置速率限制和重试机制
+- **响应格式**: 支持JSON模式等结构化输出
+
+### 工作流设计框架
+
+- **可视化节点**: 丰富的预置节点库
+- **灵活连接**: 节点间的数据流连接
+- **批量处理**: 支持列表输入的批量处理
+- **代码执行**: 内置Python代码执行节点
+- **文件处理**: 文档读取、图像处理、音频处理
+- **数据输出**: 表格、文档、图表等多种输出格式
+
+## 🔧 安装和配置
+
+### 依赖要求
+
+- Python 3.10+
+- 各模型API密钥（按需配置）
+
+### 可选依赖
+
+```bash
+# 服务器功能
+pip install vectorvein[server]
+
+# Redis缓存
+pip install vectorvein[redis]
+
+# 磁盘缓存
+pip install vectorvein[diskcache]
+
+# Google Vertex AI
+pip install vectorvein[vertex]
+
+# AWS Bedrock
+pip install vectorvein[bedrock]
+```
+
+### 设置配置
+
+```python
+from vectorvein.settings import settings
+
+# 通过字典配置（v2 版本）
+settings_dict = {
+    "rate_limit": {
+        "enabled": True,
+        "backend": "redis",  # 或 "diskcache"
+        "redis": {
+            "host": "127.0.0.1",
+            "port": 6379,
+            "db": 0,
+        },
+        "diskcache": {
+            "cache_dir": ".rate_limit_cache",
+        },
+        "default_rpm": 60,
+        "default_tpm": 1000000,
+    },
+    "endpoints": [
+        {
+            "id": "anthropic-default",
+            "api_base": "https://api.anthropic.com",
+            "api_key": "sk-ant-...",
+            "rpm": 60,
+            "tpm": 1000000,
+            "concurrent_requests": 5
+        },
+        {
+            "id": "openai-default",
+            "api_base": "https://api.openai.com/v1", 
+            "api_key": "sk-...",
+            "rpm": 3500,
+            "tpm": 90000,
+            "concurrent_requests": 10
+        },
+        {
+            "id": "qwen-default",
+            "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+            "api_key": "sk-...",
+            "rpm": 100,
+            "tpm": 1000000
+        },
+        {
+            "id": "azure-openai",
+            "region": "East US",
+            "api_base": "https://your-resource.openai.azure.com",
+            "api_key": "your-azure-key",
+            "rpm": 900,
+            "tpm": 150000,
+            "is_azure": True
+        },
+        {
+            "id": "vertex-anthropic",
+            "region": "europe-west1",
+            "api_base": "https://europe-west1-aiplatform.googleapis.com",
+            "credentials": {
+                "token": "...",
+                "refresh_token": "...",
+                "client_id": "...",
+                "client_secret": "...",
+                "quota_project_id": "your-project-id"
+            },
+            "is_vertex": True
+        }
+    ],
+    "anthropic": {
+        "models": {
+            "claude-3-7-sonnet-20250219": {
+                "id": "claude-3-7-sonnet-20250219",
+                "endpoints": ["anthropic-default"],
+                "context_length": 200000,
+                "max_output_tokens": 8192,
+                "function_call_available": True,
+                "native_multimodal": True
+            },
+            "claude-3-5-sonnet-20240620": {
+                "id": "claude-3-5-sonnet@20240620",
+                "endpoints": ["vertex-anthropic"],
+                "context_length": 200000,
+                "max_output_tokens": 8192,
+                "function_call_available": True,
+                "native_multimodal": True
+            }
+        }
+    },
+    "openai": {
+        "models": {
+            "gpt-4o": {
+                "id": "gpt-4o",
+                "endpoints": ["openai-default", "azure-openai"],
+                "context_length": 128000,
+                "max_output_tokens": 16384,
+                "function_call_available": True,
+                "response_format_available": True,
+                "native_multimodal": True
+            },
+            "gpt-4o-mini": {
+                "id": "gpt-4o-mini",
+                "endpoints": ["openai-default"],
+                "context_length": 128000,
+                "max_output_tokens": 16384,
+                "function_call_available": True,
+                "response_format_available": True,
+                "native_multimodal": True
+            }
+        }
+    },
+    "qwen": {
+        "models": {
+            "qwen3-32b": {
+                "id": "qwen3-32b", 
+                "endpoints": ["qwen-default"],
+                "context_length": 32768,
+                "max_output_tokens": 8192,
+                "function_call_available": True,
+                "response_format_available": True,
+                "native_multimodal": False
+            },
+            "qwen2.5-72b-instruct": {
+                "id": "qwen2.5-72b-instruct",
+                "endpoints": ["qwen-default"],
+                "context_length": 131072,
+                "max_output_tokens": 8192,
+                "function_call_available": True,
+                "response_format_available": True,
+                "native_multimodal": False
+            }
+        }
+    }
+}
+settings.load(settings_dict)
+
+# 或通过文件配置
+settings.load_from_file("config.json")
+```
+
+## 📖 详细文档
+
+### API 客户端详细使用
+
+#### 访问密钥管理
+
+```python
+from vectorvein.api import VectorVeinClient
+
+client = VectorVeinClient(api_key="YOUR_API_KEY")
+
+# 创建访问密钥
+keys = client.create_access_keys(
+    access_key_type="L",  # L: 长期, M: 多次, O: 一次性
+    app_id="YOUR_APP_ID",
+    count=1,
+    max_credits=500,
+    description="测试密钥"
+)
+
+# 获取访问密钥信息
+keys_info = client.get_access_keys(["ACCESS_KEY_1", "ACCESS_KEY_2"])
+
+# 列出访问密钥
+response = client.list_access_keys(
+    page=1,
+    page_size=10,
+    sort_field="create_time",
+    sort_order="descend"
+)
+
+# 更新访问密钥
+client.update_access_keys(
+    access_key="ACCESS_KEY",
+    description="更新的描述"
+)
+
+# 删除访问密钥
+client.delete_access_keys(
+    app_id="YOUR_APP_ID",
+    access_keys=["ACCESS_KEY_1", "ACCESS_KEY_2"]
+)
+```
+
+#### 生成VApp访问链接
+
+```python
+url = client.generate_vapp_url(
+    app_id="YOUR_APP_ID",
+    access_key="YOUR_ACCESS_KEY",
+    key_id="YOUR_KEY_ID"
+)
+print(f"VApp访问链接: {url}")
+```
+
+### 聊天客户端高级用法
+
+#### 工具调用（Function Calling）
+
+```python
+from vectorvein.chat_clients import create_chat_client, BackendType
+
+client = create_chat_client(BackendType.OpenAI, model="gpt-4o")
+
+tools = [{
+    "type": "function",
+    "function": {
+        "name": "get_weather",
+        "description": "获取指定城市的天气信息",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "city": {"type": "string", "description": "城市名称"}
+            },
+            "required": ["city"]
+        }
+    }
+}]
+
+response = client.create_completion(
+    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
+    tools=tools
+)
+
+if response.tool_calls:
+    for tool_call in response.tool_calls:
+        print(f"调用工具: {tool_call.function.name}")
+        print(f"参数: {tool_call.function.arguments}")
+```
+
+#### 多模态输入
+
+```python
+client = create_chat_client(BackendType.Anthropic, model="claude-3-7-sonnet-20250219")
+
+messages = [{
+    "role": "user",
+    "content": [
+        {"type": "text", "text": "这张图片里有什么？"},
+        {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": "image/jpeg",
+                "data": "base64_encoded_image_data"
+            }
+        }
+    ]
+}]
+
+response = client.create_completion(messages)
+```
+
+#### 结构化输出
+
+```python
+client = create_chat_client(BackendType.OpenAI, model="gpt-4o")
+
+response = client.create_completion(
+    messages=[{"role": "user", "content": "分析以下数据并返回JSON格式"}],
+    response_format={"type": "json_object"}
+)
+```
+
+### 工作流节点参考
+
+#### LLM 节点
+
+```python
+from vectorvein.workflow.nodes.llms import Claude, OpenAI, AliyunQwen
+
+# Claude 节点
+claude = Claude()
+claude.ports["llm_model"].value = "claude-3-7-sonnet-20250219"
+claude.ports["temperature"].value = 0.7
+claude.ports["prompt"].show = True
+
+# OpenAI 节点
+openai = OpenAI()
+openai.ports["llm_model"].value = "gpt-4o"
+openai.ports["response_format"].value = "json_object"
+
+# 通义千问节点
+qwen = AliyunQwen()
+qwen.ports["llm_model"].value = "qwen3-32b"
+```
+
+#### 文本处理节点
+
+```python
+from vectorvein.workflow.nodes.text_processing import (
+    TemplateCompose, TextSplitters, TextReplace
+)
+
+# 文本合成
+template = TemplateCompose()
+template.add_port(name="标题", port_type="text", show=True)
+template.add_port(name="内容", port_type="textarea", show=True)
+template.ports["template"].value = "# {{标题}}\n\n{{内容}}"
+
+# 文本分割
+splitter = TextSplitters()
+splitter.ports["split_method"].value = "delimiter"
+splitter.ports["delimiter"].value = "\n"
+splitter.ports["text"].show = True
+
+# 文本替换
+replacer = TextReplace()
+replacer.ports["old_text"].value = "旧文本"
+replacer.ports["new_text"].value = "新文本"
+replacer.ports["text"].show = True
+```
+
+#### 文件处理节点
+
+```python
+from vectorvein.workflow.nodes.file_processing import FileLoader
+
+loader = FileLoader()
+loader.ports["parse_quality"].value = "high"  # 高质量解析
+loader.ports["files"].show = True  # 显示文件上传界面
+```
+
+#### 输出节点
+
+```python
+from vectorvein.workflow.nodes.output import Text, Table, Document
+
+# 文本输出
+text_output = Text()
+text_output.ports["output_title"].value = "结果"
+
+# 表格输出
+table_output = Table()
+
+# 文档输出
+doc_output = Document()
+doc_output.ports["file_name"].value = "报告"
+doc_output.ports["export_type"].value = ".xlsx"
+```
+
+## 🔍 异常处理
+
+```python
+from vectorvein.api import (
+    VectorVeinAPIError, APIKeyError, WorkflowError, 
+    AccessKeyError, RequestError, TimeoutError
+)
+
+try:
+    result = client.run_workflow(wid="invalid", input_fields=[])
+except APIKeyError as e:
+    print(f"API密钥错误: {e}")
+except WorkflowError as e:
+    print(f"工作流错误: {e}")
+except TimeoutError as e:
+    print(f"请求超时: {e}")
+except VectorVeinAPIError as e:
+    print(f"API错误: {e.message}, 状态码: {e.status_code}")
+```
+
+## 🧪 测试
+
+```bash
+# 安装开发依赖
+pip install -e .[dev]
+
+# 运行测试
+pytest tests/
+
+# 运行特定测试
+pytest tests/test_simple.py -v
+
+# 生成覆盖率报告
+pytest --cov=vectorvein tests/
+```
+
+## 📝 开发指南
+
+### 项目结构
+
+```
+src/vectorvein/
+├── api/                 # VectorVein API客户端
+│   ├── client.py       # 主要客户端类
+│   ├── models.py       # 数据模型
+│   └── exceptions.py   # 异常定义
+├── chat_clients/        # 聊天客户端
+│   ├── __init__.py     # 客户端工厂函数
+│   ├── base_client.py  # 基础客户端类
+│   ├── anthropic_client.py  # Claude客户端
+│   ├── openai_client.py     # OpenAI客户端
+│   └── ...             # 其他模型客户端
+├── workflow/           # 工作流设计框架
+│   ├── graph/          # 图结构定义
+│   ├── nodes/          # 节点定义
+│   └── utils/          # 工具函数
+├── settings/           # 配置管理
+├── types/              # 类型定义
+└── utilities/          # 实用工具
+```
+
+### 贡献代码
+
+1. Fork 项目
+2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'Add amazing feature'`)
+4. 推送分支 (`git push origin feature/amazing-feature`)
+5. 创建 Pull Request
+
+### 代码规范
+
+- 使用 `ruff` 进行代码格式化和检查
+- 遵循 Python 类型提示
+- 编写测试用例覆盖新功能
+- 更新相关文档
+
+## 🤝 社区和支持
+
+- **文档**: [官方文档](https://docs.vectorvein.com)
+- **问题反馈**: [GitHub Issues](https://github.com/vectorvein/python-vectorvein/issues)
+- **讨论**: [GitHub Discussions](https://github.com/vectorvein/python-vectorvein/discussions)
+- **更新日志**: [CHANGELOG.md](CHANGELOG.md)
+
+## 📜 许可证
+
+本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
+
+## 🙏 致谢
+
+感谢所有为 VectorVein Python SDK 做出贡献的开发者和用户。
+
+---
+
+**注意事项**：
+1. 请妥善保管您的API密钥，不要将其泄露给他人
+2. API调用有速率限制，请合理使用
+3. 建议在生产环境中使用异步方式运行工作流
+4. 不同模型支持的功能可能有所差异，请参考具体模型文档