如何为你的 agent 部署添加语义搜索

语义搜索让你的 agent 能够按含义而非精确措辞来回忆已存储的记忆和文档。例如，查询 “UI preferences” 会命中一条写为 “user prefers dark interfaces” 的记忆。本指南展示如何在部署的跨线程 store 上启用语义搜索，使你的 agent 能够跨对话保留上下文，并基于先前的交互个性化响应。

前置条件

• 一个部署（参见如何为部署设置应用）以及托管选项的详细信息。
• 你的 embedding 提供商的 API key（此处为 OpenAI）。
• langchain >= 0.3.8（如果你按本指南使用字符串格式指定）。

步骤

1. 更新你的 langgraph.json 配置文件，加入 store 配置：

   {
       ...
       "store": {
           "index": {
               "embed": "openai:text-embedding-3-small",
               "dims": 1536,
               "fields": ["$"]
           }
       }
   }

   该配置会：

   • 使用 OpenAI 的 text-embedding-3-small 模型生成 embedding。
   • 将 embedding 维度设为 1536（与模型输出一致）。
   • 索引已存储数据中的所有字段（["$"] 表示索引全部字段，也可以指定具体字段，如 ["text", "metadata.title"]）。

NOTE

每个部署只支持一个 embedding 模型。LangSmith 不支持配置多个 embedding 模型，因为这会造成 /store 端点歧义并导致索引混合问题。

2. 要使用字符串 embedding 格式，请确保依赖中包含 langchain >= 0.3.8：

   # In pyproject.toml
   [project]
   dependencies = [
       "langchain>=0.3.8"
   ]

   或者，如果使用 requirements.txt：

   langchain>=0.3.8

用量

配置完成后，你可以在 nodes 中使用语义搜索。store 需要一个 namespace 元组来组织记忆：

async def search_memory(state: State, *, store: BaseStore):
    # Search the store using semantic similarity
    # The namespace tuple helps organize different types of memories
    # e.g., ("user_facts", "preferences") or ("conversation", "summaries")
    results = await store.asearch(
        namespace=("memory", "facts"),  # Organize memories by type
        query="your search query",
        limit=3  # number of results to return
    )
    return results

每个结果都是一个 SearchItem（继承 Item，并额外带有 score 字段）。配置语义搜索后，score 包含相似度分数：

results[0].key       # "07e0caf4-1631-47b7-b15f-65515d4c1843"
results[0].value     # {"text": "User prefers dark mode"}
results[0].namespace # ("memory", "facts")
results[0].score     # 0.92 (similarity score, present when semantic search is configured)

更改你的 embedding 模型

WARNING

更改 embedding 模型或维度需要重新嵌入所有现有数据。目前没有自动迁移工具。如果你需要切换模型，请提前规划。

自定义 embeddings

如果你想使用自定义 embedding，可以传入自定义 embedding 函数的路径：

{
    ...
    "store": {
        "index": {
            "embed": "path/to/embedding_function.py:embed",
            "dims": 1536,
            "fields": ["$"]
        }
    }
}

部署会在指定路径查找该函数。该函数必须是异步的，并接受字符串列表：

# path/to/embedding_function.py
from openai import AsyncOpenAI

client = AsyncOpenAI()

async def aembed_texts(texts: list[str]) -> list[list[float]]:
    """Custom embedding function that must:
    1. Be async
    2. Accept a list of strings
    3. Return a list of float arrays (embeddings)
    """
    response = await client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )
    return [e.embedding for e in response.data]

通过 API 查询

你还可以使用 LangGraph SDK 查询 store。由于 SDK 使用异步操作：

from langgraph_sdk import get_client

async def search_store():
    client = get_client()
    results = await client.store.search_items(
        ("memory", "facts"),
        query="your search query",
        limit=3  # number of results to return
    )
    return results

# Use in an async context
results = await search_store()

配置语义搜索后，每个结果项都包含 score 字段：

results["items"][0]["key"]       # "07e0caf4-1631-47b7-b15f-65515d4c1843"
results["items"][0]["value"]     # {"text": "User prefers dark mode"}
results["items"][0]["namespace"] # ["memory", "facts"]
results["items"][0]["score"]     # 0.92 (similarity score)

---