安装、注册与环境变量配置

接入即配置环境变量。LangSmith 的 Python/JS SDK 不要求你在代码里写死任何配置——它在进程启动时读取一组以 LANGSMITH_ 开头的环境变量来决定「要不要上报、报给谁、报到哪个项目、报到哪个区域」。把配置当成环境的一部分，而不是代码的一部分，是后面 CI、多环境、自托管能平滑切换的根本原因。

第一步：注册账号并创建 API Key

1. 打开 https://smith.langchain.com，用邮箱或 GitHub / Google 账号注册并登录。个人开发者有免费额度，足够跑通本教程。
2. 登录后，点击左下角头像 → Settings（设置），进入设置页。
3. 在左侧菜单选择 API Keys，点击 Create API Key（创建 API Key）。
4. 选择 key 类型：Personal Access Token（个人令牌，跟随你的账号权限，适合本地开发）或 Service Key（服务密钥，不绑定个人、适合 CI / 生产）。本教程本地开发用 Personal Access Token 即可。
5. 复制生成的 key（形如 lsv2_pt_xxxxxxxxxxxxxxxx_yyyyyyyyyy）。这个值只在创建时显示一次，关闭弹窗后无法再次查看，请立即妥善保存。
6. 顺便记下你账号所在的区域：默认美区入口是 smith.langchain.com，欧区入口是 eu.smith.langchain.com。区域决定了后面 LANGSMITH_ENDPOINT 要不要改。

第二步：安装 SDK

LangSmith 的客户端是独立的 langsmith 包，不依赖 LangChain，可以单独使用（比如你用裸 OpenAI SDK 也能上报）。如果你的应用本来就用 LangChain，再额外装 langchain，它内置了与 LangSmith 的自动集成。

# 必装：LangSmith 官方 Python SDK（含 Client、@traceable、evaluate 等）
pip install -U langsmith

# 可选：如果你的应用使用 LangChain，装它即可获得零代码自动 tracing
# langchain-core 已被 langchain 作为依赖带入；按需再装具体模型集成包
pip install -U langchain langchain-openai

# 验证安装版本（建议 langsmith >= 0.2）
python -c "import langsmith; print(langsmith.__version__)"

第三步：理解关键环境变量

写法 A：.env 文件（推荐本地开发）

# 文件名：.env （放在项目根目录，并加入 .gitignore，切勿提交）

# 上报总开关：必须为 true 才会发送 trace
LANGSMITH_TRACING=true

# 身份凭证：第一步在 Settings → API Keys 创建的值
LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx_yyyyyyyyyy

# 可选：trace 归入的项目名，不设则进 default
LANGSMITH_PROJECT=my-chatbot-dev

# 可选：区域 / 自托管 endpoint，美区可省略
# 欧区：https://eu.api.smith.langchain.com
# 自托管：填你自己的地址
LANGSMITH_ENDPOINT=https://api.smith.langchain.com

# 若用 langchain-openai 跑示例，再加上模型厂商的 key
OPENAI_API_KEY=sk-xxxxxxxx

# 加载 .env：需要 python-dotenv
#   pip install python-dotenv
from dotenv import load_dotenv

# load_dotenv 会把 .env 里的键值读进 os.environ
# 默认不覆盖已存在的同名变量；override=True 可强制覆盖
load_dotenv(override=False)

import os
# 加载后即可在代码里读取，确认变量已就位
print("tracing  =", os.environ.get("LANGSMITH_TRACING"))
print("project  =", os.environ.get("LANGSMITH_PROJECT"))
print("endpoint =", os.environ.get("LANGSMITH_ENDPOINT"))
# 注意：API key 不要直接 print 到日志，这里只示意它存在与否
print("api_key set =", bool(os.environ.get("LANGSMITH_API_KEY")))

写法 B：os.environ 显式设置（适合脚本 / Notebook）

import os
import getpass

# 关键点：这些 os.environ 赋值必须在 import langsmith / langchain 之前执行，
# 因为 SDK 在首次构建 Client 时读取这些变量。
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_PROJECT"] = "my-chatbot-dev"
# 美区可省略 endpoint；欧区 / 自托管按需设置
os.environ["LANGSMITH_ENDPOINT"] = "https://api.smith.langchain.com"

# 用 getpass 交互式输入，避免把明文 key 写进源码 / 笔记本
if not os.environ.get("LANGSMITH_API_KEY"):
    os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter LANGSMITH_API_KEY: ")

第四步：最小连通性验证

配完别急着写业务代码，先用两个层次确认连通：层次一用 Client 直接打 API，验证 key 与 endpoint 有效；层次二用 @traceable 跑一次函数调用，验证 trace 真的能上报并出现在网页项目里。

"""最小连通性验证脚本：python verify_langsmith.py
前置：已 pip install -U langsmith，且环境变量已就位（写法 A 或 B 二选一）。
"""
import os
from langsmith import Client, traceable

# ---------- 层次一：验证 API key / endpoint 是否有效 ----------
# Client 会自动从环境变量读取 api_key 与 endpoint
client = Client()

# client.info 返回服务端实例信息，能成功拿到说明认证与网络都通
info = client.info
print("[OK] 已连上 LangSmith，服务端版本:", getattr(info, "version", info))

# ---------- 层次二：验证 trace 能真正上报 ----------
# @traceable 把任意函数变成一个被追踪的 Run，自动记录输入 / 输出 / 耗时
@traceable(run_type="chain", name="verify-hello")
def hello(name: str) -> str:
    return f"hello, {name}"

result = hello("langsmith")
print("[OK] 函数返回:", result)

# 打印当前项目，方便你去网页对应项目里找这条 trace
print("[OK] trace 已上报到项目:",
      os.environ.get("LANGSMITH_PROJECT", "default"))
print("=> 打开 smith.langchain.com，进入该项目应能看到一条 verify-hello 记录")

"""可选：验证 LangChain 零代码自动接入
前置：pip install -U langchain langchain-openai，并已设置 OPENAI_API_KEY。
只要 LANGSMITH_TRACING=true，下面这段不写任何 LangSmith 代码也会自动上报 trace。
"""
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a concise assistant."),
    ("human", "{question}"),
])
model = ChatOpenAI(model="gpt-4o-mini", temperature=0)

# LCEL 管道：prompt | model。调用时 LangChain 检测到 tracing 开启，
# 会自动把这次链路（含 prompt 渲染 + 模型调用）作为一棵 trace 上报。
chain = prompt | model
resp = chain.invoke({"question": "用一句话解释什么是可观测性"})
print(resp.content)
# 回到 LangSmith 网页项目，可看到一条带 ChatPromptTemplate -> ChatOpenAI 的 trace