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

# 追踪快速入门

对于使用大型语言模型（LLM）构建的应用程序来说，[*可观测性*](/langsmith/observability-concepts) 是一个关键需求。LLM 具有非确定性，这意味着相同的提示可能产生不同的响应。这种行为使得调试和监控比传统软件更具挑战性。

LangSmith 通过提供应用程序处理请求的端到端可见性来解决这个问题。每个请求都会生成一个 [*追踪*](/langsmith/observability-concepts#traces)，它捕获了所发生事件的完整记录。追踪中包含了个别的 [*运行*](/langsmith/observability-concepts#runs)，即您的应用程序执行的具体操作，例如 LLM 调用或检索步骤。追踪运行允许您检查、调试和验证应用程序的行为。

在这个快速入门中，您将设置一个最小的 [*检索增强生成（RAG）*](https://www.mckinsey.com/featured-insights/mckinsey-explainers/what-is-retrieval-augmented-generation-rag) 应用程序，并使用 LangSmith 添加追踪功能。您将：

1. 配置您的环境。
2. 创建一个能够检索上下文并调用 LLM 的应用程序。
3. 启用追踪以捕获检索步骤和 LLM 调用。
4. 在 LangSmith UI 中查看生成的追踪。

## 先决条件

开始之前，请确保您拥有：

* **LangSmith 账户**：在 [smith.langchain.com](https://smith.langchain.com) 注册或登录。
* **LangSmith API 密钥**：按照 [创建 API 密钥](/langsmith/create-account-api-key#create-an-api-key) 指南操作。
* **OpenAI API 密钥**：从 [OpenAI 控制面板](https://platform.openai.com/account/api-keys) 生成。

本快速入门中的示例应用程序将使用 OpenAI 作为 LLM 提供商。您可以针对您应用程序的 LLM 提供商调整此示例。

<Tip>
  如果您正在使用 [LangChain](https://docs.langchain.com/oss/python/langchain/overview) 或 [LangGraph](https://docs.langchain.com/oss/python/langgraph/overview) 构建应用程序，您可以通过单个环境变量启用 LangSmith 追踪。请阅读 [使用 LangChain 追踪](/langsmith/trace-with-langchain) 或 [使用 LangGraph 追踪](/langsmith/trace-with-langgraph) 指南开始使用。
</Tip>

## 1. 创建目录并安装依赖项

在终端中，为您的项目创建一个目录并在您的环境中安装依赖项：

<CodeGroup>
  ```bash Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  mkdir ls-observability-quickstart && cd ls-observability-quickstart
  python -m venv .venv && source .venv/bin/activate
  python -m pip install --upgrade pip
  pip install -U langsmith openai
  ```

  ```bash TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  mkdir ls-observability-quickstart-ts && cd ls-observability-quickstart-ts
  npm init -y
  npm install langsmith openai typescript ts-node
  npx tsc --init
  ```
</CodeGroup>

## 2. 设置环境变量

设置以下环境变量：

* `LANGSMITH_TRACING`
* `LANGSMITH_API_KEY`
* `OPENAI_API_KEY`（或您的 LLM 提供商的 API 密钥）
* （可选）`LANGSMITH_WORKSPACE_ID`：如果您的 LangSmith API 密钥关联到多个工作空间，请设置此变量以指定要使用的工作空间。

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="<your-langsmith-api-key>"
export OPENAI_API_KEY="<your-openai-api-key>"
export LANGSMITH_WORKSPACE_ID="<your-workspace-id>"
```

如果您使用 Anthropic，请使用 [Anthropic 包装器](/langsmith/trace-anthropic) 来追踪您的调用。对于其他提供商，请使用 [可追踪包装器](/langsmith/annotate-code#use-%40traceable-%2F-traceable)。

<Note>
  要将追踪发送到特定项目，请使用 [`LANGSMITH_PROJECT` 环境变量](/langsmith/log-traces-to-project)。如果未设置此变量，LangSmith 将在追踪摄入时自动创建一个默认追踪项目。
</Note>

## 3. 定义您的应用程序

您可以使用此步骤中概述的示例应用程序代码来对一个 RAG 应用程序进行插桩。或者，您可以使用包含 LLM 调用的自己的应用程序代码。

这是一个最小的 RAG 应用程序，它直接使用 OpenAI SDK，尚未添加任何 LangSmith 追踪功能。它包含三个主要部分：

* **检索器函数**：模拟文档检索，始终返回相同的字符串。
* **OpenAI 客户端**：实例化一个普通的 OpenAI 客户端以发送聊天补全请求。
* **RAG 函数**：将检索到的文档与用户的问题结合以形成系统提示，使用 `gpt-4.1-mini` 调用 `chat.completions.create()` 端点，并返回助手的响应。

将以下代码添加到您的应用程序文件中（例如 `app.py` 或 `app.ts`）：

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from openai import OpenAI

  def retriever(query: str):
      # 最小示例检索器
      return ["Harrison worked at Kensho"]

  # OpenAI 客户端调用（尚未包装）
  client = OpenAI()

  def rag(question: str) -> str:
      docs = retriever(question)
      system_message = (
          "仅使用下面提供的信息回答用户的问题：\n"
          + "\n".join(docs)
      )

      # 此调用尚未被追踪
      resp = client.chat.completions.create(
          model="gpt-4.1-mini",
          messages=[
              {"role": "system", "content": system_message},
              {"role": "user", "content": question},
          ],
      )
      return resp.choices[0].message.content

  if __name__ == "__main__":
      print(rag("Harrison 在哪里工作？"))
  ```

  ```typescript TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import "dotenv/config";
  import OpenAI from "openai";

  // 最小示例检索器
  function retriever(query: string): string[] {
      return ["Harrison worked at Kensho"];
  }

  // OpenAI 客户端调用（尚未包装）
  const client = new OpenAI();

  async function rag(question: string) {
      const docs = retriever(question);
      const systemMessage =
          "仅使用下面提供的信息回答用户的问题：\n" +
          docs.join("\n");

      // 此调用尚未被追踪
      const resp = await client.chat.completions.create({
          model: "gpt-4.1-mini",
          messages: [
              { role: "system", content: systemMessage },
              { role: "user", content: question },
          ],
      });

      return resp.choices[0].message?.content;
  }

  (async () => {
    console.log(await rag("Harrison 在哪里工作？"));
  })();
  ```
</CodeGroup>

## 4. 追踪 LLM 调用

首先，您将追踪所有 OpenAI 调用。LangSmith 提供了包装器：

* Python：[`wrap_openai`](https://docs.smith.langchain.com/reference/python/wrappers/langsmith.wrappers._openai.wrap_openai)
* TypeScript：[`wrapOpenAI`](https://docs.smith.langchain.com/reference/js/functions/wrappers_openai.wrapOpenAI)

此代码片段包装了 OpenAI 客户端，以便每个后续的模型调用都会自动作为追踪的子运行记录到 LangSmith 中。

1. 在您的应用程序文件中包含高亮显示的行：

   <CodeGroup>
     ```python Python highlight={2,7} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     from openai import OpenAI
     from langsmith.wrappers import wrap_openai  # 追踪 openai 调用

     def retriever(query: str):
         return ["Harrison worked at Kensho"]

     client = wrap_openai(OpenAI())  # 通过包装模型调用来记录追踪

     def rag(question: str) -> str:
         docs = retriever(question)
         system_message = (
             "仅使用下面提供的信息回答用户的问题：\n"
             + "\n".join(docs)
         )
         resp = client.chat.completions.create(
             model="gpt-4.1-mini",
             messages=[
                 {"role": "system", "content": system_message},
                 {"role": "user", "content": question},
             ],
         )
         return resp.choices[0].message.content

     if __name__ == "__main__":
         print(rag("Harrison 在哪里工作？"))
     ```

     ```typescript TypeScript highlight={3,9} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     import "dotenv/config";
     import OpenAI from "openai";
     import { wrapOpenAI } from "langsmith/wrappers"; // 追踪 openai 调用

     function retriever(query: string): string[] {
         return ["Harrison worked at Kensho"];
     }

     const client = wrapOpenAI(new OpenAI()); // 通过包装模型调用来记录追踪

     async function rag(question: string) {
         const docs = retriever(question);
         const systemMessage =
             "仅使用下面提供的信息回答用户的问题：\n" +
             docs.join("\n");

         const resp = await client.chat.completions.create({
             model: "gpt-4.1-mini",
             messages: [
                 { role: "system", content: systemMessage },
                 { role: "user", content: question },
             ],
         });

         return resp.choices[0].message?.content;
     }

     (async () => {
         console.log(await rag("Harrison 在哪里工作？"));
     })();
     ```
   </CodeGroup>

2. 调用您的应用程序：

   <CodeGroup>
     ```bash Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     python app.py
     ```

     ```bash TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     npx ts-node app.ts
     ```
   </CodeGroup>

   您将收到以下输出：

   ```
   Harrison worked at Kensho.
   ```

3. 在 [LangSmith UI](https://smith.langchain.com) 中，导航到您工作空间的 **默认** 追踪项目（或您在 [步骤 2](#2-set-up-environment-variables) 中指定的工作空间）。您将看到刚刚插桩的 OpenAI 调用。

<div style={{ textAlign: 'center' }}>
  <img className="block dark:hidden" src="https://mintcdn.com/hhh-8c10bf0c/BCyPqRNhtAjzdCmk/langsmith/images/trace-quickstart-llm-call.png?fit=max&auto=format&n=BCyPqRNhtAjzdCmk&q=85&s=3a514e94feadb31a825cfda9c3e50c0c" alt="LangSmith UI 显示一个名为 ChatOpenAI 的 LLM 调用追踪，包含系统输入和人类输入，后跟 AI 输出。" width="750" height="573" data-path="langsmith/images/trace-quickstart-llm-call.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/hhh-8c10bf0c/BCyPqRNhtAjzdCmk/langsmith/images/trace-quickstart-llm-call-dark.png?fit=max&auto=format&n=BCyPqRNhtAjzdCmk&q=85&s=b1c91548472845425018c42b07ff91cf" alt="LangSmith UI 显示一个名为 ChatOpenAI 的 LLM 调用追踪，包含系统输入和人类输入，后跟 AI 输出。" width="728" height="549" data-path="langsmith/images/trace-quickstart-llm-call-dark.png" />
</div>

## 5. 追踪整个应用程序

您还可以使用 `traceable` 装饰器（[Python](https://docs.smith.langchain.com/reference/python/run_helpers/langsmith.run_helpers.traceable) 或 [TypeScript](https://reference.langchain.com/javascript/langsmith/traceable/traceable)）来追踪整个应用程序，而不仅仅是 LLM 调用。

1. 在您的应用程序文件中包含高亮显示的代码：

   <CodeGroup>
     ```python Python highlight={3,10} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     from openai import OpenAI
     from langsmith.wrappers import wrap_openai
     from langsmith import traceable

     def retriever(query: str):
         return ["Harrison worked at Kensho"]

     client = wrap_openai(OpenAI())  # 保留此项以捕获来自 LLM 的提示和响应

     @traceable
     def rag(question: str) -> str:
         docs = retriever(question)
         system_message = (
             "仅使用下面提供的信息回答用户的问题：\n"
             + "\n".join(docs)
         )
         resp = client.chat.completions.create(
             model="gpt-4.1-mini",
             messages=[
                 {"role": "system", "content": system_message},
                 {"role": "user", "content": question},
             ],
         )
         return resp.choices[0].message.content

     if __name__ == "__main__":
         print(rag("Harrison 在哪里工作？"))
     ```

     ```typescript TypeScript highlight={3,11} theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     import "dotenv/config";
     import OpenAI from "openai";
     import { wrapOpenAI, traceable } from "langsmith/wrappers";

     function retriever(query: string): string[] {
         return ["Harrison worked at Kensho"];
     }

     const client = wrapOpenAI(new OpenAI()); // 保留此项以捕获来自 LLM 的提示和响应

     const rag = traceable(async (question: string) => {
         const docs = retriever(question);
         const systemMessage =
             "仅使用下面提供的信息回答用户的问题：\n" +
             docs.join("\n");

         const resp = await client.chat.completions.create({
             model: "gpt-4.1-mini",
             messages: [
                 { role: "system", content: systemMessage },
                 { role: "user", content: question },
             ],
         });

         return resp.choices[0].message?.content;
     });

     (async () => {
         console.log(await rag("Harrison 在哪里工作？"));
     })();
     ```
   </CodeGroup>

2. 再次调用应用程序以创建运行：

   <CodeGroup>
     ```bash Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     python app.py
     ```

     ```bash TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
     npx ts-node app.ts
     ```
   </CodeGroup>

3. 返回 [LangSmith UI](https://smith.langchain.com)，导航到您工作空间的 **默认** 追踪项目（或您在 [步骤 2](#2-set-up-environment-variables) 中指定的工作空间）。您将找到整个应用程序管道的追踪，包含 **rag** 步骤和 **ChatOpenAI** LLM 调用。

<div style={{ textAlign: 'center' }}>
  <img className="block dark:hidden" src="https://mintcdn.com/hhh-8c10bf0c/BCyPqRNhtAjzdCmk/langsmith/images/trace-quickstart-app.png?fit=max&auto=format&n=BCyPqRNhtAjzdCmk&q=85&s=704707a4fd1d3b64f3ea31bd34e44568" alt="LangSmith UI 显示整个应用程序的追踪，名为 rag，包含输入后跟输出。" width="750" height="425" data-path="langsmith/images/trace-quickstart-app.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/hhh-8c10bf0c/BCyPqRNhtAjzdCmk/langsmith/images/trace-quickstart-app-dark.png?fit=max&auto=format&n=BCyPqRNhtAjzdCmk&q=85&s=05eec5b97f3f1852107efe72dcdecf98" alt="LangSmith UI 显示整个应用程序的追踪，名为 rag，包含输入后跟输出。" width="738" height="394" data-path="langsmith/images/trace-quickstart-app-dark.png" />
</div>

## 后续步骤

以下是您接下来可能想要探索的一些主题：

* [追踪集成](/langsmith/trace-with-langchain) 为各种 LLM 提供商和代理框架提供支持。
* [过滤追踪](/langsmith/filter-traces-in-application) 可以帮助您有效地导航和分析包含大量数据的追踪项目中的数据。
* [追踪 RAG 应用程序](/langsmith/observability-llm-tutorial) 是一个完整的教程，它为一个应用程序从开发到生产添加了可观测性。
* [将追踪发送到特定项目](/langsmith/log-traces-to-project) 可以更改您追踪的目标项目。

<Callout type="info" icon="feather">
  记录追踪后，使用 **[Polly](/langsmith/polly)** 对其进行分析，并获取关于应用程序性能的 AI 驱动洞察。
</Callout>

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\langsmith\observability-quickstart.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>