BigTableByteStore 集成

使用 LangChain Python 集成 BigTableByteStore 存储。

BigtableByteStore

此指南介绍如何使用 Google Cloud Bigtable 作为键值存储。

Bigtable 是一个键值对和宽列存储，适用于快速访问结构化、半结构化或非结构化数据。

概述

BigtableByteStore 使用 Google Cloud Bigtable 作为键值存储的后端。支持同步和异步操作来设置、获取和删除键值对。

集成细节

类	包	本地	JS 支持	包下载量	包最新版本
BigtableByteStore	langchain-google-bigtable	❌	❌

安装

前置条件

开始使用前，你需要一个已启用 Bigtable API 的 Google Cloud 项目。

• 创建 Google Cloud 项目
• 启用 Bigtable API
• 创建 Bigtable 实例和表

安装

集成位于 langchain-google-bigtable 包中。以下命令同时安装 langchain-google-vertexai（用于嵌入缓存示例）。

pip install -qU langchain-google-bigtable langchain-google-vertexai

设置 Google Cloud 项目

将当前笔记本设置为使用指定项目的资源。

如果你不知道项目 ID，可以运行 gcloud config list 或查看支持页面：定位项目 ID。

# @markdown Please fill in your project, instance, and table details.
PROJECT_ID = "your-gcp-project-id"  # @param {type:"string"}
INSTANCE_ID = "your-instance-id"  # @param {type:"string"}
TABLE_ID = "your-table-id"  # @param {type:"string"}

!gcloud config set project {PROJECT_ID}

认证

连接 Google Cloud 资源需要认证。

• 对于 Colab，使用下方单元格。
• 对于 Gemini 企业智能体平台工作台，请参考 配置说明。

from google.colab import auth

auth.authenticate_user()

初始化

使用 BigtableByteStore 前需确保表存在，并初始化 BigtableEngine 管理连接。

from langchain_google_bigtable import (
    BigtableByteStore,
    BigtableEngine,
    init_key_value_store_table,
)

# Ensure the table and column family exist.
init_key_value_store_table(
    project_id=PROJECT_ID,
    instance_id=INSTANCE_ID,
    table_id=TABLE_ID,
)

BigtableEngine

一个 BigtableEngine 对象管理存储的执行上下文，尤其适用于异步操作。建议初始化单个引擎并复用以提升性能。

# Initialize the engine to manage async operations.
engine = await BigtableEngine.async_initialize(
    project_id=PROJECT_ID, instance_id=INSTANCE_ID
)

BigtableByteStore

这是与键值存储交互的主类，提供数据设置、获取和删除方法。

# Initialize the store.
store = await BigtableByteStore.create(engine=engine, table_id=TABLE_ID)

使用

存储支持同步（mset、mget）和异步（amset、amget）方法，本指南使用异步版本。

设置

使用 amset 存储键值对。

kv_pairs = [
    ("key1", b"value1"),
    ("key2", b"value2"),
    ("key3", b"value3"),
]

await store.amset(kv_pairs)

获取

使用 amget 查询值。若键不存在，None 将返回对应值。

retrieved_vals = await store.amget(["key1", "key2", "nonexistent_key"])
print(retrieved_vals)

删除

使用 amdelete 移除键。

await store.amdelete(["key3"])

# Verifying the key was deleted
await store.amget(["key1", "key3"])

遍历键

使用 ayield_keys 遍历所有键或前缀匹配的键。

all_keys = [key async for key in store.ayield_keys()]
print(f"All keys: {all_keys}")

prefixed_keys = [key async for key in store.ayield_keys(prefix="key1")]
print(f"Prefixed keys: {prefixed_keys}")

高级用法：嵌入缓存

键值存储的常见用途是缓存计算成本高的操作（如文本嵌入），以节省时间和费用。

from langchain_classic.embeddings import CacheBackedEmbeddings
from langchain_google_vertexai.embeddings import VertexAIEmbeddings

underlying_embeddings = VertexAIEmbeddings(
    project=PROJECT_ID, model_name="textembedding-gecko@003"
)

# Use a namespace to avoid key collisions with other data.
cached_embedder = CacheBackedEmbeddings.from_bytes_store(
    underlying_embeddings, store, namespace="text-embeddings"
)

print("First call (computes and caches embedding):")
%time embedding_result_1 = await cached_embedder.aembed_query("Hello, world!")

print("\nSecond call (retrieves from cache):")
%time embedding_result_2 = await cached_embedder.aembed_query("Hello, world!")

作为简单文档检索器

本节演示如何使用 Bigtable 存储构建简易检索器。它充当文档持久化层，按查询前缀检索文档。

from langchain_core.retrievers import BaseRetriever
from langchain_core.documents import Document
from langchain_core.callbacks import CallbackManagerForRetrieverRun
from typing import List, Optional, Any, Union
import json


class SimpleKVStoreRetriever(BaseRetriever):
    """A simple retriever that retrieves documents based on a prefix match in the key-value store."""

    store: BigtableByteStore
    documents: List[Union[Document, str]]
    k: int

    def set_up_store(self):
        kv_pairs_to_set = []
        for i, doc in enumerate(self.documents):
            if isinstance(doc, str):
                doc = Document(page_content=doc)
            if not doc.id:
                doc.id = str(i)
            value = (
                "Page Content\n"
                + doc.page_content
                + "\nMetadata"
                + json.dumps(doc.metadata)
            )
            kv_pairs_to_set.append((doc.id, value.encode("utf-8")))
        self.store.mset(kv_pairs_to_set)

    async def _aget_relevant_documents(
        self,
        query: str,
        *,
        run_manager: Optional[CallbackManagerForRetrieverRun] = None,
    ) -> List[Document]:
        keys = [key async for key in self.store.ayield_keys(prefix=query)][: self.k]
        documents_retrieved = []
        async for document in await self.store.amget(keys):
            if document:
                document_str = document.decode("utf-8")
                page_content = document_str.split("Content\n")[1].split("\nMetadata")[0]
                metadata = json.loads(document_str.split("\nMetadata")[1])
                documents_retrieved.append(
                    Document(page_content=page_content, metadata=metadata)
                )
        return documents_retrieved

    def _get_relevant_documents(
        self,
        query: str,
        *,
        run_manager: Optional[CallbackManagerForRetrieverRun] = None,
    ) -> list[Document]:
        keys = [key for key in self.store.yield_keys(prefix=query)][: self.k]
        documents_retrieved = []
        for document in self.store.mget(keys):
            if document:
                document_str = document.decode("utf-8")
                page_content = document_str.split("Content\n")[1].split("\nMetadata")[0]
                metadata = json.loads(document_str.split("\nMetadata")[1])
                documents_retrieved.append(
                    Document(page_content=page_content, metadata=metadata)
                )
        return documents_retrieved

documents = [
    Document(
        page_content="Goldfish are popular pets for beginners, requiring relatively simple care.",
        metadata={"type": "fish", "trait": "low maintenance"},
        id="fish#Goldfish",
    ),
    Document(
        page_content="Cats are independent pets that often enjoy their own space.",
        metadata={"type": "cat", "trait": "independence"},
        id="mammals#Cats",
    ),
    Document(
        page_content="Rabbits are social animals that need plenty of space to hop around.",
        metadata={"type": "rabbit", "trait": "social"},
        id="mammals#Rabbits",
    ),
]

retriever_store = BigtableByteStore.create_sync(
    engine=engine, instance_id=INSTANCE_ID, table_id=TABLE_ID
)

KVDocumentRetriever = SimpleKVStoreRetriever(
    store=retriever_store, documents=documents, k=2
)

KVDocumentRetriever.set_up_store()

KVDocumentRetriever.invoke("fish")

KVDocumentRetriever.invoke("mammals")

API 参考

要获取 BigtableByteStore 类的完整详细信息，请查看 GitHub 上的源代码：GitHub。

---

官方原文：src/oss/python/integrations/stores/bigtable.mdx · 非官方翻译，译文由 AI 生成，以英文原文为准。