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

# 日志检索器追踪

> LangSmith 追踪中的日志检索步骤，用于文档级查看您的 RAG 管道。

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

<Note>
  这些步骤是**可选的**。如果您跳过它们，您的检索器数据仍会被记录，但 LangSmith 不会使用检索器特定的格式进行渲染。
</Note>

要启用检索器特定的渲染，请完成以下两个步骤。

## 将 `run_type` 设置为 retriever

将 [`run_type="retriever"`](/langsmith/run-data-format#run-types) 传递给 [traceable](https://reference.langchain.com/python/langsmith/run_helpers/traceable) 装饰器（Python）或 `traceable` 包装器（TypeScript）。这会告诉 LangSmith 将该步骤视为检索运行，并在 [LangSmith UI](https://smith.langchain.com) 中应用检索器特定的渲染：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langsmith import traceable

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

如果您使用的是 [RunTree API](/langsmith/annotate-code#use-the-runtree-api) 而不是 `traceable`，请在创建 `RunTree` 对象时传递 `run_type="retriever"`。

## 以预期格式返回文档

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

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

以下示例展示了应用了这两个要求的完整检索器实现：

<CodeGroup>
  ```python Python wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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):
      # 返回硬编码的占位符文档。
      # 在生产环境中，请替换为真实的向量数据库或文档索引。
      contents = ["Document contents 1", "Document contents 2", "Document contents 3"]
      return _convert_docs(contents)

  retrieve_docs("User query")
  ```

  ```typescript TypeScript wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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[] => {
      // 返回硬编码的占位符文档。
      // 在生产环境中，请替换为真实的向量数据库或文档索引。
      const contents = ["Document contents 1", "Document contents 2", "Document contents 3"];
      return convertDocs(contents);
  }, {
      name: "retrieveDocs",
      run_type: "retriever"
  });

  await retrieveDocs("User query");
  ```
</CodeGroup>

在 LangSmith UI 中，您将找到每个检索到的文档及其内容和元数据。

## 相关内容

* [为追踪注解代码](/langsmith/annotate-code)：所有追踪方法的概述，包括 `traceable`、`RunTree` 和 REST API。
* [记录 LLM 调用](/langsmith/log-llm-trace)：LLM 步骤的类似自定义记录要求。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/log-retriever-trace.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>