安装与配置

本指南将帮助你快速安装和配置 LangChain-ClickZetta 集成。

安装

使用 pip 安装（推荐）

pip install langchain-clickzetta

开发安装

如果你想从源码安装或参与开发：

git clone https://github.com/yunqiqiliang/langchain-clickzetta.git cd langchain-clickzetta/libs/clickzetta pip install -e ".[dev]"

依赖要求

Python 版本

Python 3.10 或更高版本

核心依赖

安装包时会自动安装以下依赖：

langchain-core>=0.1.0 clickzetta-connector-python>=0.8.92 clickzetta-zettapark-python>=0.1.3 sqlalchemy>=2.0.0 numpy>=1.20.0 pydantic>=2.0.0 typing-extensions>=4.0.0

可选依赖

中文AI优化（推荐）

pip install dashscope # 阿里云灵积平台

开发工具

pip install langchain-clickzetta[dev]

包含 pytest、ruff、black、mypy 等开发工具。

️ ClickZetta 环境配置

获取 ClickZetta 访问权限

注册云器科技账号
- 访问云器科技官网
- 注册并申请 ClickZetta 试用
获取连接信息 你需要以下 7 个连接参数：
- ```
service
```
  service
  - 服务地址
- ```
instance
```
  instance
  - 实例名称
- ```
workspace
```
  workspace
  - 工作空间
- ```
schema
```
  schema
  - 模式名称
- ```
username
```
  username
  - 用户名
- ```
password
```
  password
  - 密码
- ```
vcluster
```
  vcluster
  - 虚拟集群名称

环境变量配置

创建

.env

.env

文件或设置环境变量：

ClickZetta 连接配置：

export CLICKZETTA_SERVICE="your-service" export CLICKZETTA_INSTANCE="your-instance" export CLICKZETTA_WORKSPACE="your-workspace" export CLICKZETTA_SCHEMA="your-schema" export CLICKZETTA_USERNAME="your-username" export CLICKZETTA_PASSWORD="your-password" export CLICKZETTA_VCLUSTER="your-vcluster"

可选：灵积DashScope配置（推荐用于中文AI）：

export DASHSCOPE_API_KEY="your-dashscope-api-key"

连接配置文件

你也可以使用配置文件，创建

~/.clickzetta/connections.json

~/.clickzetta/connections.json

：

{ "default": { "service": "your-service", "instance": "your-instance", "workspace": "your-workspace", "schema": "your-schema", "username": "your-username", "password": "your-password", "vcluster": "your-vcluster" }, "uat": { "service": "uat-service", "instance": "uat-instance", "workspace": "test", "schema": "test_schema", "username": "test-user", "password": "test-password", "vcluster": "test-cluster" } }

验证安装

基本导入测试

测试基本导入：

try: from langchain_clickzetta import ClickZettaEngine print("✅ LangChain ClickZetta 导入成功") except ImportError as e: print(f"❌ 导入失败: {e}")

连接测试

from langchain_clickzetta import ClickZettaEngine

创建引擎实例：

engine = ClickZettaEngine( service="your-service", instance="your-instance", workspace="your-workspace", schema="your-schema", username="your-username", password="your-password", vcluster="your-vcluster" )

测试连接：

try: results, columns = engine.execute_query("SELECT 1 as test") print("✅ ClickZetta 连接成功") print(f"测试结果: {results}") except Exception as e: print(f"❌ 连接失败: {e}")

完整功能测试

from langchain_clickzetta import ( ClickZettaEngine, ClickZettaVectorStore, ClickZettaStore ) from langchain_community.embeddings import DashScopeEmbeddings

初始化组件：

engine = ClickZettaEngine( # ... 你的连接参数 )

测试向量存储：

try: embeddings = DashScopeEmbeddings( dashscope_api_key="your-api-key", model="text-embedding-v4" ) vector_store = ClickZettaVectorStore( engine=engine, embedding=embeddings, table_name="test_vectors" ) print("✅ 向量存储初始化成功") except Exception as e: print(f"⚠️ 向量存储初始化失败: {e}")

测试键值存储：

try: store = ClickZettaStore(engine=engine, table_name="test_store") print("✅ 键值存储初始化成功") except Exception as e: print(f"❌ 键值存储初始化失败: {e}")

️ 常见问题

连接问题

问题:

连接超时

连接超时

解决方案: 1. 检查网络连接 2. 确认ClickZetta服务地址正确 3. 增加connection_timeout参数

问题:

认证失败

认证失败

解决方案: 1. 确认用户名密码正确 2. 检查用户权限 3. 确认vcluster参数正确

依赖问题

问题:

ModuleNotFoundError: No module named 'clickzetta'

ModuleNotFoundError: No module named 'clickzetta'

解决方案: pip install clickzetta-connector-python

问题:

版本冲突

版本冲突

解决方案: pip install --upgrade langchain-clickzetta

权限问题

问题:

权限不足，无法创建表

权限不足，无法创建表

解决方案: 1. 联系管理员授予CREATE TABLE权限 2. 使用现有表名 3. 确认workspace和schema权限

提示

建议在生产环境使用连接池
定期更新到最新版本
使用环境变量管理敏感信息
开启日志记录以便调试

联系我们