如何为你的智能体部署添加语义搜索

语义搜索使你的智能体能够根据含义而非精确措辞来召回存储的记忆和文档。例如，查询“UI偏好”会找到一份写为“用户偏好深色界面”的记忆。本指南将向你展示如何在你的部署的跨线程存储上启用语义搜索，以便你的智能体能够在对话间保持上下文，并基于先前的交互来个性化响应。

前提条件

一个部署（参考如何为部署设置应用程序）以及托管选项的详细信息。
你的嵌入服务提供商（在本例中是 OpenAI）的 API 密钥。
langchain >= 0.3.8（如果你在本指南中使用字符串格式指定）。

步骤

更新你的 langgraph.json 配置文件，以包含存储配置：
{ ... "store": { "index": { "embed": "openai:text-embedding-3-small", "dims": 1536, "fields": ["$"] } } }
此配置：
- 使用 OpenAI 的 text-embedding-3-small 模型生成嵌入向量。
- 将嵌入维度设置为 1536（与模型的输出匹配）。
- 为存储数据中的所有字段建立索引（["$"] 表示为所有内容建立索引，或指定特定字段如 ["text", "metadata.title"]）。
每个部署仅支持一个嵌入模型。LangSmith 不支持配置多个嵌入模型，因为这会导致 /store 端点产生歧义并引发混合索引问题。
若要使用字符串嵌入格式，请确保你的依赖项包含 langchain >= 0.3.8：
# 在 pyproject.toml 中 [project] dependencies = [ "langchain>=0.3.8" ]
或者，如果使用 requirements.txt：
langchain>=0.3.8

用法

配置完成后，你可以在你的节点中使用语义搜索。存储需要一个命名空间元组来组织记忆：

async def search_memory(state: State, *, store: BaseStore):
    # 使用语义相似性搜索存储
    # 命名空间元组有助于组织不同类型的记忆
    # 例如，("user_facts", "preferences") 或 ("conversation", "summaries")
    results = await store.asearch(
        namespace=("memory", "facts"),  # 按类型组织记忆
        query="your search query",
        limit=3  # 要返回的结果数量
    )
    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（相似性分数，在配置了语义搜索时存在）

更改你的嵌入模型

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

自定义嵌入

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

{
    ...
    "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]]:
    """自定义嵌入函数，必须：
    1. 是异步的
    2. 接受一个字符串列表
    3. 返回一个浮点数数组（嵌入向量）的列表
    """
    response = await client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )
    return [e.embedding for e in response.data]

通过 API 查询

你也可以使用 LangGraph SDK 来查询存储。由于 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  # 要返回的结果数量
    )
    return results

# 在异步上下文中使用
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（相似性分数）

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Develop your application

Capabilities

How to build

Auth & access control

Server customization

如何为你的智能体部署添加语义搜索

前提条件

步骤

用法

更改你的嵌入模型

自定义嵌入

通过 API 查询

​前提条件

​步骤

​用法

​更改你的嵌入模型

​自定义嵌入

​通过 API 查询

前提条件

步骤

用法

更改你的嵌入模型

自定义嵌入

通过 API 查询