记录 retriever trace

在 LangSmith trace 中记录检索步骤，以便对 RAG 管道进行文档级可见性分析。

许多 LLM 应用会在检索增强生成（RAG）管道中从向量数据库、知识图谱或其他索引检索文档。LangSmith 为 retriever 步骤提供专门的渲染，使你更容易检查检索到的文档并诊断检索问题。

NOTE

这些步骤是可选的。如果跳过它们，你的 retriever 数据仍会被记录，但 LangSmith 不会使用 retriever 专用格式进行渲染。

要启用 retriever 专用渲染，请完成以下两个步骤。

将 run_type 设置为 retriever

将 run_type="retriever" 传给 traceable 装饰器（Python）或 traceable 包装器（TypeScript）。这会告诉 LangSmith 将该步骤视为检索 run，并在 LangSmith UI 中应用 retriever 专用渲染：

from langsmith import traceable

@traceable(run_type="retriever")
def retrieve_docs(query):
    ...

如果你使用的是 RunTree API 而不是 traceable，请在创建 RunTree 对象时传入 run_type="retriever"。

以预期格式返回文档

从 retriever 函数返回字典列表（Python）或对象列表（TypeScript）。列表中的每一项代表一个检索到的文档，并且必须包含以下字段：

字段	类型	描述
page_content	string	检索到的文档的文本内容。
type	string	必须始终为 "Document"。
metadata	object	包含文档元数据的键值对，例如源 URL、chunk ID 或分数。此元数据会与文档一起显示在 trace 中。

以下示例展示了一个应用了这两项要求的完整 retriever 实现：

Python

from langsmith import traceable

def _convert_docs(results):
    return [
        {
            "page_content": r,
            "type": "Document",
            "metadata": {"foo": "bar"}
        }
        for r in results
    ]

@traceable(run_type="retriever")
def retrieve_docs(query):
    # Returning hardcoded placeholder documents.
    # In production, replace with a real vector database or document index.
    contents = ["Document contents 1", "Document contents 2", "Document contents 3"]
    return _convert_docs(contents)

retrieve_docs("User query")

TypeScript

import { traceable } from "langsmith/traceable";

interface Document {
    page_content: string;
    type: string;
    metadata: { foo: string };
}

function convertDocs(results: string[]): Document[] {
    return results.map((r) => ({
        page_content: r,
        type: "Document",
        metadata: { foo: "bar" }
    }));
}

const retrieveDocs = traceable((query: string): Document[] => {
    // Returning hardcoded placeholder documents.
    // In production, replace with a real vector database or document index.
    const contents = ["Document contents 1", "Document contents 2", "Document contents 3"];
    return convertDocs(contents);
}, {
    name: "retrieveDocs",
    run_type: "retriever"
});

await retrieveDocs("User query");

在 LangSmith UI 中，你会看到每个检索到的文档及其内容和元数据。

相关

• 为追踪标注代码：概述所有追踪方法，包括 traceable、RunTree 和 REST API。
• 记录 LLM 调用：LLM 步骤类似的自定义日志记录要求。

---