---

一、开篇导读

欢迎来到《LangSmith从入门到精通》专栏的第2节课。在上节课中，我们学习了LangSmith的基本概念、工作原理，并成功运行了第一个追踪项目。相信你已经体会到了链路追踪带来的便利——从黑盒到白盒，大模型应用的每一个步骤都清晰可见。

然而，在实际使用过程中，你可能已经遇到了一些困惑：免费版到底能用多久？超出配额会怎样？如果我想邀请团队成员一起使用，应该怎么操作？不同的付费版本有什么区别？企业级应用需要哪些额外的功能？

本节课将为你彻底解答这些问题。我们会从零开始，详细讲解LangSmith的账号体系、权限模型、计费规则，以及免费版的使用限制。更重要的是，我们会通过实际代码和案例，让你亲身体验如何查看配额使用情况、如何管理成员权限、如何估算成本。

本节课你将收获：

• 掌握LangSmith账号注册的完整流程(包括Google、GitHub、邮箱三种方式)
• 理解组织的概念以及如何创建和管理组织
• 掌握API Key的生成、使用、撤销和安全管理
• 清晰了解免费版、专业版(Pro)、企业版(Enterprise)的功能差异和价格
• 学会如何监控配额使用情况，避免超额
• 了解团队成员的权限体系(Owner、Admin、Writer、Reader等)
• 掌握通过Python SDK查询用量和管理的技巧
• 了解企业客户如何与LangSmith签订合同和获取发票

二、知识前置铺垫

在深入LangSmith的账号和计费体系之前，我们需要先理解几个基础概念。

2.1 SaaS服务的通用模型

LangSmith采用的是SaaS(软件即服务)模式。简单来说，你不需要自己搭建服务器、安装软件、维护数据库，LangSmith官方已经做好了这一切，你只需要注册账号，通过互联网使用即可。

SaaS服务通常采用订阅制收费，类似于视频会员(按月或按年付费)。不同等级的会员享有不同的功能和配额。

SaaS服务的关键概念：

• 租户(Tenant)：每个注册的账号/组织是一个租户，租户之间的数据完全隔离。你可以理解为在同一个小区里，每家每户的房间号不同，钥匙不能互开。

• 配额(Quota)：在订阅周期内(通常是一个月)，你可以使用的资源上限。例如免费版每月只能发送1000次Trace。

• 计量(Metering)：系统会记录你实际使用了多少资源。就像水表记录用水量一样，LangSmith会记录你发了多少Trace、执行了多少次评估。

• 超限(Over-limit)：当使用量超过配额时，服务商会采取行动，比如拒绝新请求、降级功能、或者自动升级套餐。

2.2 为什么需要区分免费版和付费版

对于个人开发者/学习者：

• 免费版足以满足学习和小型项目需求
• 1000次Trace/月，每天约33次，用于开发和调试足够了
• 无需信用卡，零成本入门

对于创业团队：

• 专业版(Pro)提供更高的配额(如10000次Trace/月)
• 支持团队成员协作(多人查看和管理)
• 更长的数据保留期(30天 vs 7天)
• 支持优先邮件支持

对于企业客户：

• 企业版提供高级安全特性(SAML SSO、审计日志)
• 私有化部署选项(数据不出公司)
• 按需定制配额(每月数百万次Trace)
• SLA服务等级协议保障(99.9%可用性)
• 专门的客户成功经理

理解这些区别，可以帮助你根据自身情况选择合适的套餐，避免为不需要的功能付费，也避免因配额不足影响开发进度。

2.3 免费版的商业逻辑

你可能会好奇：LangSmith为什么要提供免费版？公司不会亏本吗？

免费版的商业目的包括：

1. 降低入门门槛：让开发者可以零成本试用，体验产品价值
2. 培养用户习惯：当你习惯了LangSmith的便利，进入企业后会更倾向于推荐购买
3. 收集反馈：大量免费用户的使用数据可以帮助团队发现bug和改进产品
4. 社区建设：免费用户也是社区的一部分，可以贡献教程、回答新手问题

免费版的成本(服务器、带宽、存储)相对可控，而转化的付费用户带来的收入足以覆盖。这是一种常见的**PLG(产品驱动增长)**策略。

三、核心概念精讲

3.1 账号(Account)与组织(Organization)

首先需要厘清LangSmith中的两个重要概念：账号和组织。

账号(Account) 是你登录LangSmith的身份凭证。每个账号有唯一的邮箱地址。

组织(Organization) 是资源的集合。一个组织可以包含多个项目(Project)、数据集(Dataset)、成员(Member)等。

关系和层级：

账号(个人身份)
    ↓ 创建/加入
组织(Team)
    ↓ 包含
项目(Project)、数据集(Dataset)、成员

实际场景：

• 如果你个人使用：你的账号下会自动创建一个以你用户名命名的组织(如zhang_san)。你在这个组织内创建项目。
• 如果你是团队成员：你的账号会被邀请加入公司的组织(如acme_inc)。你在这个组织下工作。

为什么需要组织？
因为一个开发者可能同时为多个公司/项目工作。通过组织，你可以方便地在不同上下文间切换：

• 组织A：工作项目(需要付费订阅)
• 组织B：个人学习(免费版)
• 组织C：开源项目贡献(免费版)

3.2 成员(Member)与角色(Role)

成员 是指被邀请加入组织的用户。一个用户可以属于多个组织，在不同的组织中可能拥有不同的角色。

角色 决定了成员在组织内能做什么。LangSmith目前有以下几种角色(权限从高到低)：

角色	权限范围	典型用途
Owner	组织所有者，拥有最高权限：可以删除组织、管理订阅、邀请/移除任何成员、修改所有人角色	公司技术负责人
Admin	管理员：可以管理成员(邀请、移除普通成员)、管理项目、管理API Key，但不能删除组织或修改Owner	团队Leader
Writer	写入者：可以创建/修改项目、运行评估、创建数据集、发送Trace，但不能管理成员或API Key	核心开发者
Reader	只读者：只能查看数据和Trace，不能做任何修改	产品经理、QA、实习生

权限设计的原则：最小权限原则——给每个成员恰好完成工作所需的最少权限，降低误操作风险。

3.3 API Key与个人访问令牌

API Key 是你通过程序访问LangSmith服务的凭证。它不需要用户名和密码，只需要一个字符串。

API Key与登录密码的区别：

• 登录密码用于Web界面，可以修改组织设置、管理成员
• API Key用于程序调用，通常只有读写数据的权限(不能管理用户)
• API Key可以随时撤销和重新生成，不影响登录密码

最佳实践：

• 每个应用/服务使用独立的API Key(比如dev-key、prod-key、cicd-key)
• 定期轮换API Key(比如每90天重新生成)
• 不要将API Key硬编码在代码中，始终使用环境变量

3.4 订阅(Subscription)与计费周期

订阅 是组织级别的付费计划。一个组织只能有一种订阅(免费、Pro、Enterprise)。

计费周期：

• 月度订阅：每月自动扣费，适合短期项目或灵活调整
• 年度订阅：每年一次性支付，通常有20%左右的折扣

计费方式：

• 大部分套餐采用固定配额模式，超出部分要么拒绝服务，要么按量额外计费
• 企业版通常采用定制合同，按年签约，包含一定量的配额，超出部分协商价格

四、原理底层剖析

4.1 身份认证流程

当你通过代码调用LangSmith API时，后台的认证流程如下：

你的代码 → 设置HTTP Header: x-api-key: lsv2_xxx → LangSmith API → 验证Key有效性 → 检查Key关联的组织 → 检查组织的订阅状态 → 检查配额 → 处理请求

Step 1: 客户端设置Header

# LangSmith SDK内部实现(伪代码)
headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json"
}

Step 2: API Gateway验证Key
LangSmith使用API Gateway统一入口，它会：

• 检查API Key的格式是否正确
• 查询数据库确认Key是否存在且未撤销
• 提取Key关联的organization_id

Step 3: 检查订阅和配额

• 根据organization_id查询当前订阅计划
• 从Redis计数器读取本月已使用的Trace数量
• 判断是否超过配额限制

Step 4: 处理请求

• 如果通过所有检查，请求被转发到后端服务
• 如果失败，返回HTTP 429(配额超限)或401(认证失败)

4.2 配额计数机制

LangSmith如何统计你的使用量？这涉及到计数器和窗口的概念。

计数器(Counter)：一个累加数字，每发生一次事件就加1。LangSmith会维护以下几个关键计数器(每个组织独立)：

• traces_this_month：本月已记录的Trace数量
• evaluations_this_month：本月已执行的评估任务次数
• storage_bytes：当前存储的数据总量(用于控制保留期)

时间窗口(Window)：配额按月重置。LangSmith采用日历月方式(每月1号重置)还是滚动月方式(注册日开始算30天)？

根据官方文档和用户反馈，LangSmith采用的是日历月重置：每月1日UTC时间00:00重置配额。这意味着：

• 1月31日注册，只有1天的配额(可能会浪费)
• 2月1日注册，有整月的配额

计数时机：

• Trace：在chain.invoke()执行完成后，数据成功写入LangSmith数据库时计数
• 评估：当评估任务完成时计数(不是开始时)

边界情况：

• 如果某个Trace写入失败(如网络问题)，是否计数？不计数。
• 如果某个Trace很大(如包含10MB的输入)，是否特殊计费？目前没有，免费版同样计数1次。

4.3 权限校验的实现

LangSmith的权限模型基于RBAC(基于角色的访问控制)。每个API请求都会附带API Key，服务端从中解析出角色，然后判断是否允许操作。

权限矩阵(简化版)：

操作	Owner	Admin	Writer	Reader
查看Trace	✅	✅	✅	✅
创建Project	✅	✅	✅	❌
删除Project	✅	✅	❌	❌
邀请成员	✅	✅	❌	❌
移除成员	✅	✅	❌	❌
修改订阅	✅	❌	❌	❌
删除组织	✅	❌	❌	❌

为什么Writer不能删除Project？
删除Project是破坏性操作，应该只有Admin及以上才能执行。Writer专注于开发工作，不应该有权限删除整个项目的数据。

4.4 数据隔离原理

在多租户SaaS中，数据隔离至关重要——你的数据绝对不能泄露给另一个组织。

LangSmith的实现方式：

• 数据库中的每个表都有organization_id字段
• 所有查询都自动添加WHERE organization_id = ?条件
• API层验证用户的organization_id与请求的资源是否匹配

示例(伪SQL)：

-- 查询某个Project的Runs
SELECT * FROM runs 
WHERE project_id = ? 
  AND organization_id = (SELECT organization_id FROM api_keys WHERE key = ?)

如果用户试图访问不属于自己组织的Project，查询会返回空结果，而不是报错(防止信息泄露)。

五、环境配置手把手实战

5.1 注册LangSmith账号(三种方式)

方式一：使用Google账号注册(推荐)

1. 访问 https://smith.langchain.com
2. 点击 “Continue with Google”
3. 选择你的Google账号(如果没有登录，先登录)
4. 授权LangSmith访问你的基本信息(邮箱、姓名)
5. 系统自动跳转到控制台

方式二：使用GitHub账号注册

1. 点击 “Continue with GitHub”
2. 登录GitHub(如果需要)
3. 授权LangSmith读取你的GitHub邮箱和公开信息
4. 完成注册

方式三：使用邮箱注册

1. 点击 “Sign up with email”
2. 输入姓名、邮箱、密码
3. 查收验证邮件，点击链接验证邮箱
4. 完成注册

注册后的初始状态：

• 系统自动创建一个组织，名称是你的用户名(如li_ming)
• 你的账号在该组织中拥有Owner角色
• 订阅状态为免费版(Free)

5.2 完善个人资料

登录后，建议立即完善以下信息：

1. 头像和显示名称：点击右上角头像 → Settings → Profile → 上传头像、设置显示名称
2. 时区：设置正确的时区(如Asia/Shanghai)，这样控制台的时间显示更友好
3. 邮箱验证：如果使用邮箱注册，确保已验证(未验证账号可能有限制)

5.3 创建第一个API Key

步骤1：进入API Keys页面
左侧菜单 → Settings → API Keys → 点击 “Create API Key”

步骤2：填写信息

• Name：my-dev-key(清晰的命名)
• Expiration：可以选择永不过期(但建议设置90天)
• Permissions：选择All或者根据需要选择特定项目

步骤3：保存Key
复制生成的Key(格式：lsv2_pt_xxxxxxxxxxxxx)。重视警告：LangSmith不会再次显示完整Key，一旦丢失只能删除重建。

步骤4：测试Key
使用以下命令测试Key是否有效：

curl -X GET https://api.smith.langchain.com/api/v1/sessions \
  -H "x-api-key: lsv2_pt_xxxxx"

返回200说明Key有效。

5.4 查看免费版配额

在控制台查看当前使用情况：

路径：Settings → Billing & Usage

你会看到类似这样的界面：

Plan: Free
Monthly trace usage: 47 / 1000 (4.7%)
Monthly evaluation usage: 0 / 100 (0%)
Data retention: 7 days

重要指标解释：

• Monthly trace usage：本月已使用的Trace次数。免费版上限1000。
• Monthly evaluation usage：本月已运行的评估任务次数。免费版上限100(注意，不是1000)。
• Data retention：数据保留期。免费版7天后自动删除。

剩余天数提醒：页面会显示距离下次配额重置还有多少天。

5.5 升级到专业版(可选，演示流程)

如果你决定升级，流程如下(注：需要绑定信用卡，但你可以只走流程不实际支付)：

1. 在Billing页面点击 “Upgrade to Pro”
2. 选择计费周期：Monthly($39/月) 或 Yearly($390/年，节省约17%)
3. 填写支付信息(Stripe支付)
4. 确认升级

注意：专业版采用预付费模式，按周期自动续费。取消订阅后，当前周期结束后降级为免费版。

六、完整可运行代码案例

6.1 通过Python SDK查询配额使用情况

LangSmith提供了官方的Python SDK，可以用来程序化查询配额信息。

# 文件名: check_quota.py
# 说明: 通过API查询当前配额使用情况

import os
from dotenv import load_dotenv
from langsmith import Client

load_dotenv()

# 初始化LangSmith客户端
# 会自动从环境变量读取 LANGCHAIN_API_KEY
client = Client()

def get_usage_stats():
    """
    获取当前组织的使用统计数据
    """
    # 获取当前组织信息
    org_info = client.request_helper(
        "GET",
        "/api/v1/organizations/current",
        data=None
    )
    
    print(f"组织名称: {org_info.get('display_name')}")
    print(f"组织ID: {org_info.get('id')}")
    
    # 获取用量信息
    # 注意: 这个API可能随版本变化，这里使用通用方法
    usage = client.request_helper(
        "GET",
        "/api/v1/usage",
        data=None
    )
    
    print(f"\n📊 本月用量统计:")
    print(f"  - 追踪次数: {usage.get('traces', 0)} / {usage.get('trace_limit', 1000)}")
    print(f"  - 评估次数: {usage.get('evaluations', 0)} / {usage.get('evaluation_limit', 100)}")
    print(f"  - 数据保留: {usage.get('retention_days', 7)} 天")
    
    percent_trace = (usage.get('traces', 0) / usage.get('trace_limit', 1)) * 100
    percent_eval = (usage.get('evaluations', 0) / usage.get('evaluation_limit', 1)) * 100
    
    if percent_trace > 80:
        print(f"  ⚠️ 警告: Trace使用量已达 {percent_trace:.1f}%，接近配额上限")
    if percent_eval > 80:
        print(f"  ⚠️ 警告: 评估使用量已达 {percent_eval:.1f}%，接近配额上限")
    
    return usage

if __name__ == "__main__":
    try:
        stats = get_usage_stats()
    except Exception as e:
        print(f"❌ 获取用量失败: {e}")
        print("请确认API Key有效且有权限")

注意：上述代码中的API路径可能随时间变化，实际使用时请参考官方文档。更稳定的方式是使用LangSmith SDK中封装的方法。

6.2 模拟配额超限并观察行为

这个示例会运行大量Trace，故意消耗配额(注意：会消耗你的实际配额，谨慎运行！建议在测试组织或即将重置配额前运行)。

# 文件名: simulate_quota_exceed.py
# 警告: 运行此脚本会消耗大量配额，请确保你理解后果

import os
import time
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.prompts import PromptTemplate

load_dotenv()

# 可选: 创建一个临时项目，避免污染主要项目
os.environ["LANGCHAIN_PROJECT"] = "quota_test"

def run_single_trace(i: int):
    """
    运行单次追踪
    """
    print(f"运行第 {i} 次追踪...", end="", flush=True)
    try:
        llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
        prompt = PromptTemplate.from_template("请用一句话介绍{thing}")
        chain = prompt | llm
        result = chain.invoke({"thing": "LangSmith"})
        print(f" ✅ 成功")
        return True
    except Exception as e:
        error_msg = str(e)
        if "quota" in error_msg.lower() or "limit" in error_msg.lower():
            print(f" ❌ 配额超限: {error_msg}")
            return False
        else:
            print(f" ❌ 其他错误: {error_msg}")
            return False

def main():
    # 循环运行直到配额用完或达到最大次数
    MAX_TRIES = 1050  # 超过1000次配额
    success_count = 0
    
    for i in range(1, MAX_TRIES + 1):
        success = run_single_trace(i)
        if success:
            success_count += 1
        else:
            print(f"\n停止测试，成功运行 {success_count} 次")
            break
        
        # 避免请求过快，每10次休息1秒
        if i % 10 == 0:
            time.sleep(1)
    
    print(f"\n📊 统计: 成功 {success_count} 次")

if __name__ == "__main__":
    confirm = input("⚠️ 此脚本会消耗大量配额(最多1050次)。继续吗？(yes/no): ")
    if confirm.lower() == "yes":
        main()
    else:
        print("已取消")

预期结果：

• 前1000次全部成功
• 第1001次开始，LangSmith API返回HTTP 429或特定的错误消息，提示配额超限
• 你的应用代码会收到异常，可以根据异常类型做降级处理

6.3 团队管理脚本示例

通过Python SDK管理团队成员(需要Owner或Admin权限)。

# 文件名: team_management.py
# 说明: 通过API邀请和移除成员

import os
from dotenv import load_dotenv
from langsmith import Client

load_dotenv()

client = Client()

def invite_member(email: str, role: str = "reader"):
    """
    邀请用户加入组织
    role: owner, admin, writer, reader
    """
    # 注意: 实际API可能不同，请查阅官方文档
    data = {
        "email": email,
        "role": role
    }
    
    try:
        response = client.request_helper(
            "POST",
            "/api/v1/organizations/invite",
            data=data
        )
        print(f"✅ 邀请已发送至 {email}，角色: {role}")
        return response
    except Exception as e:
        print(f"❌ 邀请失败: {e}")
        return None

def list_members():
    """
    列出所有组织成员
    """
    members = client.request_helper(
        "GET",
        "/api/v1/organizations/members",
        data=None
    )
    
    print("\n👥 组织成员列表:")
    for member in members.get("members", []):
        print(f"  - {member['email']} ({member['role']}) {'(Owner)' if member.get('is_owner') else ''}")
    
    return members

def remove_member(email: str):
    """
    移除成员
    """
    try:
        client.request_helper(
            "DELETE",
            f"/api/v1/organizations/members/{email}",
            data=None
        )
        print(f"✅ 已移除 {email}")
    except Exception as e:
        print(f"❌ 移除失败: {e}")

if __name__ == "__main__":
    # 示例: 列出当前成员
    list_members()
    
    # 示例: 邀请新成员(请替换为真实邮箱)
    # invite_member("colleague@example.com", role="writer")

重要说明：LangSmith的Python SDK目前对团队管理的API支持可能不完整，上述代码作为思路参考。实际操作建议通过Web界面进行。

6.4 用量告警脚本

在生产环境中，你可能希望在配额达到阈值时收到告警。可以使用以下脚本配合cron定时任务。

# 文件名: quota_alert.py
# 说明: 检查配额使用率，超过阈值发送告警(示例使用webhook)

import os
import requests
from dotenv import load_dotenv
from langsmith import Client

load_dotenv()

def check_quota_and_alert():
    """
    检查配额，如果超过阈值发送钉钉/飞书/企业微信通知
    """
    client = Client()
    
    # 获取用量(伪代码，需要根据实际API调整)
    usage = get_usage_from_api(client)  # 自定义函数
    
    trace_used = usage['traces']
    trace_limit = usage['trace_limit']
    trace_percent = (trace_used / trace_limit) * 100
    
    eval_used = usage['evaluations']
    eval_limit = usage['evaluation_limit']
    eval_percent = (eval_used / eval_limit) * 100
    
    alerts = []
    if trace_percent > 80:
        alerts.append(f"Trace配额已使用 {trace_percent:.1f}% ({trace_used}/{trace_limit})")
    if eval_percent > 80:
        alerts.append(f"评估配额已使用 {eval_percent:.1f}% ({eval_used}/{eval_limit})")
    
    if alerts:
        send_alert("\n".join(alerts))
    else:
        print("配额正常")

def send_alert(message: str):
    """
    发送告警到Webhook(以钉钉为例)
    """
    webhook_url = os.getenv("DINGTALK_WEBHOOK")  # 需要在.env配置
    if not webhook_url:
        print("未配置告警webhook")
        print(f"告警内容: {message}")
        return
    
    data = {
        "msgtype": "text",
        "text": {"content": f"【LangSmith配额告警】\n{message}"}
    }
    requests.post(webhook_url, json=data)

if __name__ == "__main__":
    check_quota_and_alert()

七、代码逐行详解

7.1 check_quota.py 核心部分解析

client = Client()

• Client是LangSmith SDK的核心类，封装了所有API调用
• 初始化时会自动从环境变量读取LANGCHAIN_API_KEY
• 如果未找到Key，会抛出LangSmithError

org_info = client.request_helper(
    "GET",
    "/api/v1/organizations/current",
    data=None
)

• request_helper是底层HTTP请求方法
• /organizations/current 端点返回当前API Key所属的组织信息
• 返回的org_info包含id、display_name、plan(套餐类型)等字段

usage = client.request_helper("GET", "/api/v1/usage", data=None)

• /usage端点返回使用量统计
• 实际项目中，更推荐使用client.read_usage()(如果SDK提供)
• 注意：某些API可能需要特定的权限(Writer及以上)

percent_trace = (usage.get('traces', 0) / usage.get('trace_limit', 1)) * 100

• 除法时需要处理分母为0的情况，这里用trace_limit默认1避免除零
• 注意整数除法问题：Python 3中/返回浮点数，所以不需要特殊处理

7.2 simulate_quota_exceed.py 关键点

os.environ["LANGCHAIN_PROJECT"] = "quota_test"

• 在运行前修改环境变量，将数据发送到临时Project
• 这样做的好处：配额消耗记录在临时项目中，不影响你日常使用的项目统计

def run_single_trace(i: int):
    llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)

• 每次循环都重新创建ChatOpenAI和Chain实例
• 这不是高效的做法，但为了测试配额，简单实现即可

if "quota" in error_msg.lower() or "limit" in error_msg.lower():

• 根据错误消息判断是否配额超限
• 实际生产中应该检查HTTP状态码(429)或错误类型

7.3 关于API端点的不确定性

重要提醒：LangSmith的API处于活跃开发中，端点路径、请求/响应格式可能随时变化。上述代码中的端点(/api/v1/usage等)可能在实际运行时失效。

更可靠的方式：

1. 使用LangSmith SDK提供的官方方法：client.read_usage() (如果存在)
2. 查阅官方最新API文档：https://docs.smith.langchain.com/
3. 使用浏览器开发者工具，从Web界面的网络请求中观察实际API调用

八、常见坑点与避坑指南

8.1 API Key泄露

症状：收到异常流量通知，或者发现你的配额被大量消耗。

原因：API Key被意外提交到公开Git仓库、分享到聊天群、或者被恶意软件窃取。

解决方案：

• 立即在Settings → API Keys中撤销泄露的Key
• 生成新的Key并更新所有使用位置
• 检查是否有未授权的项目或Run

预防措施：

# 在.gitignore中添加
.env
*.key
secrets/

# 使用pre-commit钩子扫描密钥
# 安装detect-secrets等工具

8.2 免费版配额提前耗尽

症状：中下旬就无法发送新Trace，影响开发和测试。

原因：

• 在循环或自动化测试中无意识地大量调用
• 开发环境频繁调试，每次调试都产生Trace

解决方案：

• 开发时使用环境变量选择性启用追踪
• 使用采样策略(见第1课)
• 将测试和开发分离到不同Project，分别计数

降级处理代码：

def safe_invoke(chain, input_data):
    try:
        return chain.invoke(input_data)
    except Exception as e:
        if "quota" in str(e):
            print("配额超限，降级为无追踪模式")
            # 临时禁用追踪
            os.environ["LANGCHAIN_TRACING_V2"] = "false"
            result = chain.invoke(input_data)
            os.environ["LANGCHAIN_TRACING_V2"] = "true"
            return result
        else:
            raise

8.3 团队成员角色设置不当

症状：

• 新成员无法创建Project(但他们需要这个权限)
• 或者新成员误删了重要项目(因为权限过高)

解决方案：

• 大多数开发者应该赋予Writer角色
• 只有负责管理权限的人赋予Admin
• Owner仅保留给组织创建者
• 给产品、测试人员赋予Reader

角色检查清单：

- [ ] 团队成员A(后端开发): Writer
- [ ] 团队成员B(前端开发): Writer  
- [ ] 团队成员C(算法工程师): Writer
- [ ] 团队Leader: Admin
- [ ] 产品经理: Reader
- [ ] QA测试: Reader
- [ ] 实习生: Reader

8.4 升级套餐后未立即生效

症状：已经支付升级费用，但控制台仍然显示免费版限制。

原因：

• 支付处理有延迟(通常几分钟)
• 需要刷新页面或重新登录
• 可能是浏览器缓存问题

解决方案：

• 等待5-10分钟
• 强制刷新页面(Ctrl+F5)
• 退出登录，清除缓存，重新登录
• 如果仍未生效，联系support@langchain.com

8.5 多组织混淆

症状：切换组织后，发现之前的数据“消失”了。

原因：每个组织的数据完全隔离。你当前登录的是组织A，当然看不到组织B的项目。

解决方案：

• 左上角组织切换器：点击下拉菜单切换组织
• 确保API Key对应的组织正确：API Key属于特定组织，不能跨组织使用

调试技巧：

from langsmith import Client
client = Client()
# 查看当前API Key所属组织
print(client._get_tenant_id())  # 内部方法，谨慎使用

8.6 同一台机器多个API Key冲突

症状：明明设置了不同的环境变量，但永远使用同一个Key。

原因：LangSmith SDK在首次导入时读取环境变量并缓存。后续修改os.environ无效。

解决方案：

# 错误的方式
import os
os.environ["LANGCHAIN_API_KEY"] = "key1"
from langsmith import Client  # 已经读取了key1

os.environ["LANGCHAIN_API_KEY"] = "key2"  # 无效
client2 = Client()  # 仍然使用key1

# 正确的方式: 在导入前设置
import os
os.environ["LANGCHAIN_API_KEY"] = "key2"
from langsmith import Client
client2 = Client()  # 使用key2

# 或者使用配置对象
from langsmith import Client
client = Client(api_key="key1")
client2 = Client(api_key="key2")

九、企业级落地最佳实践

9.1 多组织架构设计

对于中大型企业，建议采用以下组织架构：

顶层组织: Acme Corp (企业主组织)
    ├── 子组织: Acme-Research (研发部门)
    ├── 子组织: Acme-Product (产品部门)
    └── 子组织: Acme-Ops (运维部门)

为什么不建议把所有项目放在同一个组织？

• 计费隔离：不同部门可能有独立的预算和订阅
• 权限隔离：研发部门不应看到运维部门的监控数据
• 数据分类：避免混乱

如何在多个组织间切换？

• Web界面：左上角组织切换器
• API：不同的API Key绑定不同组织

9.2 企业版私有化部署评估

如果你是金融、医疗、政府等对数据合规要求极高的行业，可能需要私有化部署。

私有化部署的优势：

• 数据完全在内网，满足合规要求
• 可以定制功能
• 性能可控

私有化部署的挑战：

• 需要自己维护服务器、数据库、备份
• 升级需要自己操作
• 成本较高(通常是年度合同，六位数起)

何时考虑私有化：

• 公司政策禁止数据离开境内/内网
• 每月Trace量超过1000万，SaaS成本过高
• 需要与内部监控系统深度集成

9.3 成本估算公式

如果你正在评估预算，可以使用以下公式估算：

月度总成本 = 基础订阅费 + 超额费用(如有)

其中：

• 基础订阅费：Pro版 $39/月，Enterprise 协商
• 超额费用：Pro版超出配额后，每1000 Trace约$10(示例价格，需确认)

示例计算：

预计月Trace量: 5000
Pro套餐包含: 10000 Trace
总成本: $39/月 (未超额)

预计月Trace量: 25000
Pro套餐包含: 10000
超出: 15000
超出费用: 15000/1000 * $10 = $150
总成本: $39 + $150 = $189/月

省钱技巧：

• 使用采样减少Trace量(例如只采样10%)
• 优化代码，合并细粒度Run
• 签订年度合同获得折扣

9.4 审计日志的合规要求

对于上市公司或受监管行业，审计日志是必备功能。

LangSmith企业版提供的审计日志包括：

• 谁在什么时间创建/删除了Project
• 谁修改了API Key
• 谁邀请了/移除了成员
• 谁修改了订阅计划

如何导出审计日志：
企业版通常支持通过API导出，或集成到SIEM系统(如Splunk、Datadog)。

9.5 发票与支付流程

个人/团队使用：

• 通过Stripe支付，支持信用卡(Visa、Mastercard、Amex)
• 支付后自动开具电子发票(发送到注册邮箱)
• 支持变更账单信息(公司名称、税号)

企业客户：

• 联系销售(sales@langchain.com)签订合同
• 支持银行转账、PO(采购订单)
• 可开具增值税专用发票(需提供税号)
• 按月/按年结算

取消订阅的注意事项：

• Pro版取消订阅后，当前周期结束时降级为免费版
• 超出免费版限制的数据会被清除或不可访问
• 建议在取消前导出重要数据(通过API批量下载Run)

十、本节知识点总结

本节课我们深入学习了LangSmith的账号体系和计费规则：

账号与组织：

• 账号是你的身份凭证，组织是资源容器
• 一个账号可以加入多个组织，在不同组织可能有不同角色
• 组织是计费和配额的基本单位

角色权限：

• Owner: 最高权限，可删除组织
• Admin: 可管理成员和项目
• Writer: 可创建和修改数据
• Reader: 只读权限
• 遵循最小权限原则分配角色

API Key：

• 用于程序访问，不要泄露
• 可以设置过期时间，定期轮换
• 每个应用使用独立的Key

计费规则：

• 免费版: 1000 Trace/月，100次评估/月，7天保留
• Pro版: $39/月起，包含更多配额和功能
• Enterprise: 定制报价，包含私有化等高级功能
• 按日历月重置配额

配额管理：

• 可Web界面查看使用量
• 可通过API查询用量编写告警脚本
• 超出配额会拒绝服务，需要降级处理

团队协作：

• 通过邮箱邀请成员加入组织
• 不同角色协同工作
• 支持多组织架构隔离部门

十一、课后思考练习题

练习题1：理论理解

1.1 请列举至少3个场景，你会建议使用专业版(Pro)而不是免费版。

1.2 假设你是公司技术负责人，团队成员10人(全部为开发者)，你希望他们都能创建Project、运行评估，但不能随意删除Project或邀请外部人员。你应该给每个成员分配什么角色？

1.3 解释为什么即使API Key被泄露，攻击者也无法删除你的组织(假设你不是Owner)？

练习题2：动手实践

2.1 使用你现有的LangSmith账号，通过Web界面完成以下操作：

• 创建一个名为test-org-移除测试的临时组织(使用完删除)
• 邀请一个朋友的邮箱(可以是你的另一个邮箱)加入该组织，角色为Reader
• 从Reader角色升级为Writer
• 最后将该成员移除

2.2 编写一个Python脚本，实现以下功能：

• 自动检查当前组织的Trace配额使用百分比
• 如果超过90%，发送邮件告警(可以使用SMTP库或第三方邮件API)
• 将脚本添加到cron定时任务，每天运行一次

练习题3：场景设计

3.1 你的团队正在开发一个RAG应用，每天预计有1000个用户请求。为了调试和优化，你需要追踪其中5%的请求(抽样)。请设计一个方案：

• 如何在代码中实现5%随机采样？
• 如何确保采样对配额的影响可控？
• 如果某天流量暴增到5000请求/天，你的采样策略会如何调整？

3.2 公司采购部门要求你提供LangSmith企业版的预算估算。已知：

• 每天约10万次用户请求
• 每次请求会产生1个Trace(包含5-10个Run)
• 需要90天数据保留期
• 需要满足GDPR合规

请估算月度费用(参考Pro版价格和超额费用)，并说明是否需要企业版。

练习题4：API探索(选做)

4.1 查阅LangSmith官方API文档(https://api.smith.langchain.com/openapi.json 或类似地址)，找到以下操作对应的API端点：

• 列出当前组织下的所有Projects
• 创建新的Project
• 删除指定的Project

4.2 使用curl命令或Python的requests库，直接调用上述API(使用你的API Key)，验证能否操作成功。

提交方式：

• 将答案和代码整理成文档
• 在评论区分享你的学习心得
• 参考答案将在下节课公布

---

下节课预告：

第3课我们将进入实战开发环境搭建——从零开始配置Python虚拟环境、安装LangChain和LangSmith依赖、配置全局参数。我们会覆盖Windows、macOS、Linux三个平台的差异，确保每个人都能成功配置。

此外，还会讲解如何使用poetry和pipenv依赖管理，以及Docker容器化部署的最佳实践。

请确保你已经注册好LangSmith账号并拿到了API Key，下节课我们需要这些凭证。如果你在注册过程中遇到问题，请在评论区留言，我会第一时间解答。

下一节课见！

---

🔗《20节课 LangSmith 从入门到精通》系列课程导航

去订阅

🌟 感谢您耐心阅读到这里！
💡 如果本文对您有所启发欢迎：
👍 点赞📌 收藏 📤 分享给更多需要的伙伴。
🗣️ 期待在评论区看到您的想法, 共同进步。
🔔 关注我，持续获取更多干货内容～
🤗 我们下篇文章见～