> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# BigTableByteStore 集成

> 使用 LangChain Python 集成 BigTableByteStore 存储。

# BigtableByteStore

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

[Bigtable](https://cloud.google.com/bigtable) 是一个键值对和宽列存储，适用于快速访问结构化、半结构化或非结构化数据。

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googleapis/langchain-google-bigtable-python/blob/main/docs/key_value_store.ipynb)

## 概述

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

### 集成细节

| 类 | 包 | 本地 | JS 支持 | 包下载量 | 包最新版本 |
| :- | :- | :-: | :-: | :-: | :-: |
| [`BigtableByteStore`](https://github.com/googleapis/langchain-google-bigtable-python/blob/main/src/langchain_google_bigtable/key_value_store.py) | [`langchain-google-bigtable`](https://pypi.org/project/langchain-google-bigtable/) | ❌ | ❌ | ![PyPI - Downloads](https://img.shields.io/pypi/dm/langchain-google-bigtable?style=flat-square\&label=%20) | ![PyPI - Version](https://img.shields.io/pypi/v/langchain-google-bigtable) |

## 安装

### 前置条件

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

* [创建 Google Cloud 项目](https://developers.google.com/workspace/guides/create-project)
* [启用 Bigtable API](https://console.cloud.google.com/flows/enableapi?apiid=bigtable.googleapis.com)
* [创建 Bigtable 实例和表](https://cloud.google.com/bigtable/docs/creating-instance)

### 安装

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

```python theme={null}
pip install -qU langchain-google-bigtable langchain-google-vertexai
```

### 设置 Google Cloud 项目

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

如果你不知道项目 ID，可以运行 `gcloud config list` 或查看支持页面：[定位项目 ID](https://support.google.com/googleapi/answer/7014113)。

```python theme={null}
# @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 企业智能体平台工作台**，请参考 [配置说明](https://github.com/GoogleCloudPlatform/generative-ai/tree/main/setup-env)。

```python theme={null}
from google.colab import auth

auth.authenticate_user()
```

## 初始化

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

```python theme={null}
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` 对象管理存储的执行上下文，尤其适用于异步操作。建议初始化单个引擎并复用以提升性能。

```python theme={null}
# Initialize the engine to manage async operations.
engine = await BigtableEngine.async_initialize(
    project_id=PROJECT_ID, instance_id=INSTANCE_ID
)
```

### BigtableByteStore

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

```python theme={null}
# Initialize the store.
store = await BigtableByteStore.create(engine=engine, table_id=TABLE_ID)
```

## 使用

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

### 设置

使用 `amset` 存储键值对。

```python theme={null}
kv_pairs = [
    ("key1", b"value1"),
    ("key2", b"value2"),
    ("key3", b"value3"),
]

await store.amset(kv_pairs)
```

### 获取

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

```python theme={null}
retrieved_vals = await store.amget(["key1", "key2", "nonexistent_key"])
print(retrieved_vals)
```

### 删除

使用 `amdelete` 移除键。

```python theme={null}
await store.amdelete(["key3"])

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

### 遍历键

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

```python theme={null}
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}")
```

## 高级用法：嵌入缓存

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

```python theme={null}
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"
)
```

```python theme={null}
print("First call (computes and caches embedding):")
%time embedding_result_1 = await cached_embedder.aembed_query("Hello, world!")
```

```python theme={null}
print("\nSecond call (retrieves from cache):")
%time embedding_result_2 = await cached_embedder.aembed_query("Hello, world!")
```

### 作为简单文档检索器

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

```python theme={null}
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
```

```python theme={null}
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",
    ),
]
```

```python theme={null}
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()
```

```python theme={null}
KVDocumentRetriever.invoke("fish")
```

```python theme={null}
KVDocumentRetriever.invoke("mammals")
```

## API 参考

要获取 `BigtableByteStore` 类的完整详细信息，请查看 GitHub 上的源代码：[GitHub](https://github.com/googleapis/langchain-google-bigtable-python/blob/main/src/langchain_google_bigtable/key_value_store.py)。

***

> 官方原文：[src/oss/python/integrations/stores/bigtable.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/python/integrations/stores/bigtable.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.