跳到主要内容
这是一项测试版功能。API 在未来版本中可能会发生变化。
LangSmith 收集器-代理是一个轻量级、高性能的代理服务器，它位于您的应用程序和 LangSmith 后端之间。它在将追踪数据发送到 LangSmith 之前对其进行批处理和压缩，从而减少网络开销并提高性能。

​
何时使用收集器-代理

收集器-代理在以下情况下特别有价值：
  • 您正在并行运行应用程序的多个实例，并且需要高效地聚合追踪
  • 您希望获得比直接通过 OTEL API 调用 LangSmith 更高效的追踪（收集器优化了批处理和压缩）
  • 您正在使用的语言没有原生的 LangSmith SDK

​
主要特点

  • 高效数据传输 将多个 span 批量上传为更少、更大的文件。
  • 压缩 使用 zstd 最小化有效载荷大小。
  • OTLP 支持 通过 HTTP POST 接受 OTLP JSON 和 Protobuf。
  • 语义转换 将 GenAI/OpenInference 约定映射到 LangSmith 运行模型。
  • 灵活批处理 按 span 数量或时间间隔刷新。

​
配置

通过环境变量配置
变量描述默认
HTTP_PORT运行代理服务器的端口4318
LANGSMITH_ENDPOINTLangSmith 后端 URLhttps://api.smith.langchain.com
LANGSMITH_API_KEYLangSmith 的 API 密钥必填（环境变量或请求头）
LANGSMITH_PROJECT默认追踪项目如果未指定，则为默认项目
BATCH_SIZE每次上传批次的 span 数量100
FLUSH_INTERVAL_MS刷新间隔（毫秒）1000
MAX_BUFFER_BYTES最大未压缩缓冲区大小10485760 (10 MB)
MAX_BODY_BYTES最大传入请求正文大小209715200 (200 MB)
MAX_RETRIES失败上传的重试次数3
RETRY_BACKOFF_MS初始回退（毫秒）100

​
项目配置

收集器-代理支持 LangSmith 项目配置，优先级如下：
  1. 如果在请求头中指定了项目（Langsmith-Project），则使用该项目
  2. 如果请求头中未指定项目，则使用 LANGSMITH_PROJECT 环境变量中设置的项目
  3. 如果两者都未设置，则追踪到 default 项目。

​
身份验证

API 密钥可以通过以下方式提供：
  • 作为环境变量（LANGSMITH_API_KEY）
  • 在请求头中（X-API-Key）

​
部署 (Docker)

您可以使用 Docker 部署收集器-代理
  1. 构建镜像 
    docker build \
  -t langsmith-collector-proxy:beta .
  2. 运行容器 
    docker run -d \
  -p 4318:4318 \
  -e LANGSMITH_API_KEY=<your_api_key> \
  -e LANGSMITH_PROJECT=<your_project> \
  langsmith-collector-proxy:beta

​
用法

将任何兼容 OTLP 的客户端或 OpenTelemetry 收集器导出器指向： 
export OTEL_EXPORTER_OTLP_ENDPOINT=http://<host>:4318/v1/traces
export OTEL_EXPORTER_OTLP_HEADERS="X-API-Key=<your_api_key>,Langsmith-Project=<your_project>"
发送测试追踪 
curl -X POST https://:4318/v1/traces \
  -H "Content-Type: application/json" \
  --data '{
    "resourceSpans": [
      {
        "resource": {
          "attributes": [
            {
              "key": "service.name",
              "value": { "stringValue": "test-service" }
            }
          ]
        },
        "scopeSpans": [
          {
            "scope": {
              "name": "example/instrumentation",
              "version": "1.0.0"
            },
            "spans": [
              {
                "traceId": "T6nh/mMkIONaoHewS9UWIw==",
                "spanId": "0tEqJwCpvU0=",
                "name": "parent-span",
                "kind": "SPAN_KIND_INTERNAL",
                "startTimeUnixNano": 1747675155185223936,
                "endTimeUnixNano":   1747675156185223936,
                "attributes": [
                  {
                    "key": "gen_ai.prompt",
                    "value": {
                      "stringValue": "{\"text\":\"Hello, world!\"}"
                    }
                  },
                  {
                    "key": "gen_ai.usage.input_tokens",
                    "value": {
                      "intValue": "5"
                    }
                  },
                  {
                    "key": "gen_ai.completion",
                    "value": {
                      "stringValue": "{\"text\":\"Hi there!\"}"
                    }
                  },
                  {
                    "key": "gen_ai.usage.output_tokens",
                    "value": {
                      "intValue": "3"
                    }
                  }
                ],
                "droppedAttributesCount": 0,
                "events": [],
                "links": [],
                "status": {}
              }
            ]
          }
        ]
      }
    ]
  }'

​
健康与扩展

  • 活跃度: GET /live → 200
  • 就绪状态: GET /ready → 200

​
横向扩展

为确保完整追踪正确批处理，请将具有相同追踪 ID 的 span 路由到同一个实例（例如，通过一致性哈希）。

​
分支与扩展

在 GitHub 上 Fork 收集器-代理仓库 并实现您自己的转换器
  • 创建自定义 GenAiConverter 或修改 internal/translator/otel_converter.go 中现有的转换器
  • 在 internal/translator/translator.go 中注册自定义转换器
在 GitHub 上编辑此页面源文件。
以编程方式连接这些文档到 Claude、VSCode 等，通过 MCP 获取实时答案。
© . This site is unofficial and not affiliated with LangChain, Inc.