5分钟上手指南
本指南将在 5 分钟内带你体验 LangChain-ClickZetta 的核心功能。
目标
完成本指南后，你将能够：
- 建立ClickZetta连接
- 执行自然语言SQL查询
- 创建向量存储并进行相似性搜索
- 使用键值存储保存数据
前提条件
- 已安装
langchain-clickzetta
langchain-clickzetta
- 已获得 ClickZetta 连接参数
- （可选）灵积DashScope API密钥
第一步：建立连接
from langchain_clickzetta import ClickZettaEngine
创建ClickZetta引擎：
engine = ClickZettaEngine(
service="your-service",
instance="your-instance",
workspace="your-workspace",
schema="your-schema",
username="your-username",
password="your-password",
vcluster="your-vcluster"
)
测试连接：
results, columns = engine.execute_query("SELECT CURRENT_TIMESTAMP as now")
print(f"连接成功！当前时间: {results[0]['now']}")
第二步：自然语言SQL查询
from langchain_clickzetta import ClickZettaSQLChain
from langchain_community.llms import Tongyi
初始化大语言模型：
llm = Tongyi(
dashscope_api_key="your-dashscope-api-key",
model_name="qwen-plus"
)
创建SQL链：
sql_chain = ClickZettaSQLChain.from_engine(
engine=engine,
llm=llm,
return_sql=True
)
用自然语言查询数据库：
response = sql_chain.invoke({
"query": "显示数据库中所有的表"
})
print("AI回答:", response["result"])
print("生成的SQL:", response["sql_query"])
第三步：向量存储与相似性搜索
from langchain_clickzetta import ClickZettaVectorStore
from langchain_community.embeddings import DashScopeEmbeddings
from langchain_core.documents import Document
初始化嵌入模型：
embeddings = DashScopeEmbeddings(
dashscope_api_key="your-dashscope-api-key",
model="text-embedding-v4"
)
创建向量存储：
vector_store = ClickZettaVectorStore(
engine=engine,
embedding=embeddings,
table_name="quickstart_vectors"
)
添加一些文档：
documents = [
Document(page_content="云器ClickZetta是新一代云原生湖仓一体化平台"),
Document(page_content="LangChain是构建AI应用的开发框架"),
Document(page_content="向量搜索可以实现语义相似性检索"),
Document(page_content="ClickZetta支持实时数据分析和处理")
]
将文档添加到向量存储：
vector_store.add_documents(documents)
print("✅ 文档已添加到向量存储")
进行相似性搜索：
query = "什么是ClickZetta？"
results = vector_store.similarity_search(query, k=2)
print(f"\n搜索查询: {query}")
for i, doc in enumerate(results, 1):
print(f"{i}. {doc.page_content}")
第四步：键值存储
from langchain_clickzetta import ClickZettaStore
创建键值存储：
store = ClickZettaStore(
engine=engine,
table_name="quickstart_store"
)
存储一些键值对：
data = [
("user:123", b"张三"),
("config:app", b'{"theme": "dark", "language": "zh"}'),
("cache:result", b"计算结果缓存数据")
]
store.mset(data)
print("✅ 数据已存储")
检索数据：
keys = ["user:123", "config:app", "cache:result"]
values = store.mget(keys)
for key, value in zip(keys, values):
if value:
print(f"{key}: {value.decode('utf-8')}")
第五步：混合搜索（向量+全文）
from langchain_clickzetta import ClickZettaHybridStore, ClickZettaUnifiedRetriever
创建混合存储（单表支持向量+全文索引）：
hybrid_store = ClickZettaHybridStore(
engine=engine,
embedding=embeddings,
table_name="quickstart_hybrid",
text_analyzer="ik" # 中文分词器
)
添加中文文档：
chinese_docs = [
Document(page_content="人工智能正在改变世界，深度学习是其核心技术"),
Document(page_content="云计算提供了可扩展的计算资源"),
Document(page_content="大数据分析帮助企业做出更好的决策"),
Document(page_content="机器学习算法可以从数据中学习模式")
]
hybrid_store.add_documents(chinese_docs)
创建统一检索器：
retriever = ClickZettaUnifiedRetriever(
hybrid_store=hybrid_store,
search_type="hybrid", # 混合搜索
alpha=0.5, # 向量搜索和全文搜索的权重平衡
k=3
)
执行混合搜索：
query = "AI和机器学习"
results = retriever.invoke(query)
print(f"\n混合搜索查询: {query}")
for i, doc in enumerate(results, 1):
print(f"{i}. {doc.page_content}")
第六步：聊天历史
from langchain_clickzetta import ClickZettaChatMessageHistory
from langchain_core.messages import HumanMessage, AIMessage
创建聊天历史管理：
chat_history = ClickZettaChatMessageHistory(
engine=engine,
session_id="user_demo",
table_name="quickstart_chat"
)
添加对话消息：
chat_history.add_message(HumanMessage(content="你好，我想了解ClickZetta"))
chat_history.add_message(AIMessage(content="你好！ClickZetta是云器科技推出的新一代云原生湖仓一体化平台，具有10倍性能提升的特点。"))
chat_history.add_message(HumanMessage(content="它有什么特色功能？"))
chat_history.add_message(AIMessage(content="ClickZetta的特色包括：1）增量计算引擎 2）统一存储计算 3）实时数据处理 4）云原生架构。"))
print("✅ 对话历史已保存")
检索对话历史：
messages = chat_history.messages
print(f"\n对话历史 (共{len(messages)}条消息):")
for msg in messages:
speaker = "用户" if msg.__class__.__name__ == "HumanMessage" else "AI"
print(f"{speaker}: {msg.content}")
完成！
恭喜！你已经在5分钟内体验了 LangChain ClickZetta 的主要功能：
✅ 数据库连接 - 建立了与 ClickZetta 的连接
✅ AI SQL 查询 - 使用自然语言查询数据库
✅ 向量搜索 - 实现了语义相似性检索
✅ 键值存储 - 存储和检索结构化数据
✅ 混合搜索 - 结合向量和全文搜索
✅ 聊天历史 - 管理对话记忆
实用提示
- 性能优化：在生产环境中使用连接池。
- 安全性：使用环境变量管理 API 密钥。
- 监控：启用日志记录以便调试。
- 扩展性：考虑表分区和索引优化。
