---
type: study
status: verified
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
tags:
  - study
  - langchain
  - python
  - integrations
  - key-value-store
  - cache
topic: LangChain Python 键值存储缓存与字节持久化
sources:
  - https://docs.langchain.com/oss/python/integrations/stores
  - https://docs.langchain.com/oss/python/integrations/stores/astradb
  - https://docs.langchain.com/oss/python/integrations/stores/bigtable
  - https://docs.langchain.com/oss/python/integrations/stores/elasticsearch
  - https://docs.langchain.com/oss/python/integrations/stores/file_system
  - https://docs.langchain.com/oss/python/integrations/stores/in_memory
last_verified: 2026-08-11
---
# Key-Value Stores：缓存与字节持久化

## 公共接口

`BaseStore` 面向批量键值操作，主要用于 embedding cache：

- `mget(keys) -> list[bytes | None]`，缺失位置返回 `None`；
- `mset([(key, bytes), ...])`；
- `mdelete(keys)`；
- `yield_keys(prefix=None)`。

批量是核心语义，可减少网络往返；但公共接口没有跨 key 事务、CAS、TTL、版本、加密或 exactly-once 保证。

## 6 个路由

| 路由 | 包/类 | 持久化与限制 |
|---|---|---|
| `stores` | 总索引 | 说明 BaseStore 和本地实现；还列出未在本站展开的社区 stores。 |
| `astradb` | `langchain-astradb` / `AstraDBByteStore` | Astra endpoint/token，远程持久化，提供批量 get/set/delete。 |
| `bigtable` | `langchain-google-bigtable` / `BigtableByteStore` | sync/async `m*`/`am*`，`ayield_keys`；复用一个 `BigtableEngine` 管理 async 执行上下文。 |
| `elasticsearch` | `langchain-elasticsearch` / `ElasticsearchEmbeddingsCache` | 远程持久 cache；缓存向量默认不可搜索，如需 searchable vector 必须子类化并只做 additive mapping/document 扩展。 |
| `file_system` | `langchain-classic` / `LocalFileStore` | 单机目录持久化，适合能容忍文件被外部增删的场景；不提供分布式一致性。 |
| `in_memory` | `langchain-core` / `InMemoryByteStore` | Python dict，进程退出丢失，只适合测试或不要求持久化的场景。 |

## Cache key 与一致性

Embedding cache key 必须包含规范化 input hash、embedding provider/model/version、dimension、预处理版本和 tenant/namespace；否则升级模型或跨租户时会命中错误向量。值应带 schema version 和校验和，反序列化前限制大小和类型。

`mset` 的批量接口不证明原子性。对远程 store 要验证 partial failure、重试、重复写和读后写一致性；对 `yield_keys` 不假设稳定 snapshot，也避免在请求路径全量扫描。删除/过期和数据主体请求需要可观测且可验证，不能只依赖自然淘汰。

LocalFileStore 需独占或应用级锁、受限根目录和原子 rename 策略；多进程/多主机不要共享未声明并发语义的普通目录。Elasticsearch cache 的认证、TLS、index mapping 与生命周期策略应由运维配置，而不是把示例密码写进代码。

## 验证边界

已逐页核对 6 个官方 Markdown 路由和明确的 sync/async/persistence 边界。未对后端进行并发、故障、TTL、备份或恢复测试；BaseStore 本身也不承诺这些能力。