vectorvein 0.3.63

VectorVein Python SDK

VectorVein Python SDK

VectorVein Python SDK 是一个功能强大的 Python 库，提供了对向量脉络(VectorVein)平台的完整访问能力。它包含两大核心功能：

1. 向量脉络 API 客户端 - 用于调用向量脉络的工作流和VApp功能
2. 多模型聊天客户端 - 统一的接口支持多种大语言模型（Claude、OpenAI、通义千问、智谱AI等）
3. 工作流设计框架 - 用于构建和设计复杂的AI工作流

🚀 快速开始

安装

pip install vectorvein

基本使用

1. VectorVein API 客户端

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. 聊天客户端

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. 工作流设计

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密钥（按需配置）

可选依赖

# 服务器功能
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]

设置配置

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 客户端详细使用

访问密钥管理

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访问链接

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）

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}")

多模态输入

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)

结构化输出

client = create_chat_client(BackendType.OpenAI, model="gpt-4o")

response = client.create_completion(
    messages=[{"role": "user", "content": "分析以下数据并返回JSON格式"}],
    response_format={"type": "json_object"}
)

工作流节点参考

LLM 节点

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"

文本处理节点

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

文件处理节点

from vectorvein.workflow.nodes.file_processing import FileLoader

loader = FileLoader()
loader.ports["parse_quality"].value = "high"  # 高质量解析
loader.ports["files"].show = True  # 显示文件上传界面

输出节点

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"

🔍 异常处理

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}")

🧪 测试

# 安装开发依赖
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 类型提示
• 编写测试用例覆盖新功能
• 更新相关文档

🤝 社区和支持

• 文档: 官方文档
• 问题反馈: GitHub Issues
• 讨论: GitHub Discussions
• 更新日志: CHANGELOG.md

📜 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

感谢所有为 VectorVein Python SDK 做出贡献的开发者和用户。

---

注意事项：

1. 请妥善保管您的API密钥，不要将其泄露给他人
2. API调用有速率限制，请合理使用
3. 建议在生产环境中使用异步方式运行工作流
4. 不同模型支持的功能可能有所差异，请参考具体模型文档