追踪 Amazon Bedrock 应用

本指南介绍如何使用原生 AWS SDK 通过 LangSmith 追踪 Amazon Bedrock 模型调用。LangSmith 也可与 LangChain 的 Bedrock 集成无缝协作。两种方法都能提供以下洞察：

• 请求和响应负载
• token 使用量和成本
• 延迟和性能指标
• 用于筛选和分析的自定义标签和元数据
• 多步链和智能体工作流

安装

pip

pip install boto3 langsmith

npm

npm install @aws-sdk/client-bedrock-runtime langsmith

此集成使用原生 AWS SDK 和 LangSmith 的追踪能力。对于 Python，你将使用 boto3（适用于 Python 的 AWS SDK）以及 langsmith 来捕获追踪。对于 JavaScript/TypeScript，你将使用 @aws-sdk/client-bedrock-runtime 与 langsmith 包。两种实现都使用 Bedrock Converse API，它提供与基础模型交互的统一接口。

设置

要启用 LangSmith 追踪，请配置 LangSmith API key 和项目设置。你还需要设置 AWS 凭据以通过 Bedrock 进行认证。

LangSmith 配置

export LANGSMITH_API_KEY=<your_langsmith_api_key>
export LANGSMITH_PROJECT=<your_project_name> # optional, defaults to "default"
export LANGSMITH_TRACING=true

你可以前往 Settings > API Keys，从 smith.langchain.com 获取 LangSmith API key。LANGSMITH_PROJECT 变量允许你将追踪组织到不同项目中。

AWS 凭据

配置 AWS 凭据以通过 Bedrock 进行认证。你需要一个已启用 Bedrock 访问权限的 AWS 账户。请遵循 AWS 设置说明创建凭据，并启用模型访问：

export AWS_ACCESS_KEY_ID=<your_aws_access_key_id>
export AWS_SECRET_ACCESS_KEY=<your_aws_secret_key>
export AWS_SESSION_TOKEN=<your_session_token> # only if using temporary credentials
export AWS_DEFAULT_REGION=<your_bedrock_region> # e.g., us-east-1 or us-west-2

配置追踪

设置环境变量后，你可以通过使用 LangSmith 的 @traceable 装饰器（Python）或 traceable 函数（TypeScript）包装调用函数，来追踪 Bedrock 模型调用。

以下示例演示如何将 Bedrock Converse API 与 LangSmith 追踪一起使用。Converse API 是 AWS 推荐的基础模型统一接口，可在不同模型提供商之间提供一致的请求和响应处理。你可以使用自定义标签和元数据增强追踪——标签帮助你对追踪进行分类（例如按环境、功能或测试类型），而元数据允许你附加任意键值对以提供详细上下文：

Python

import boto3
from langsmith import traceable

# Initialize Bedrock runtime client (ensure AWS creds and region are set)
bedrock = boto3.client("bedrock-runtime", region_name="us-east-1")
model_id = "anthropic.claude-haiku-4-5-20251001-v1:0"  # Example Bedrock model ID

# Decorate the model invocation function to auto-capture a trace with tags/metadata
@traceable(tags=["aws-bedrock", "langsmith", "integration-test"],
           metadata={"env": "dev", "model_provider": "bedrock", "model_id": "claude-3-haiku"})
def generate_text(prompt: str) -> str:
    # Prepare a single-turn conversation input for the Converse API
    messages = [
        {"role": "user", "content": [{"text": prompt}]}
    ]
    # Invoke the Bedrock model using the unified Converse API
    response = bedrock.converse(
        modelId=model_id,
        messages=messages,
        inferenceConfig={"maxTokens": 512, "temperature": 0.5, "topP": 0.9}
    )
    # Extract the model's reply text from the response
    output_text = response["output"]["message"]["content"][0]["text"]
    return output_text

# Call the traced function with a prompt
result = generate_text("How can I trace AWS Bedrock model outputs to LangSmith for debugging?")
print(result)

TypeScript

import { BedrockRuntimeClient, ConverseCommand } from "@aws-sdk/client-bedrock-runtime";
import { traceable } from "langsmith";

const client = new BedrockRuntimeClient({ region: "us-east-1" });
const modelId = "anthropic.claude-haiku-4-5-20251001-v1:0";

// Wrap the Bedrock invocation in a traceable function with tags and metadata
const invokeBedrock = traceable(
  async (userInput: string) => {
    // Prepare the conversation message for the Bedrock Converse API
    const conversation = [
      { role: "user", content: [{ text: userInput }] }
    ];
    // Create and send a Bedrock Converse command (single-turn chat)
    const command = new ConverseCommand({
      modelId,
      messages: conversation,
      inferenceConfig: { maxTokens: 512, temperature: 0.5, topP: 0.9 }
    });
    const response = await client.send(command);
    // Extract the assistant's reply text from the response
    const outputText = response.output?.message?.content[0]?.text;
    return outputText;
  },
  {
    tags: ["aws-bedrock", "langsmith", "integration-test"],
    metadata: { env: "dev", model_provider: "bedrock", model_id: "claude-3-haiku" }
  }
);

// Invoke the traced function with a prompt
const answer = await invokeBedrock("How can I trace AWS Bedrock model outputs to LangSmith for debugging?");
console.log(answer);

• boto3.client("bedrock-runtime") 创建一个 Bedrock Runtime 客户端。
• converse 方法将聊天提示词（以消息列表形式）发送到指定模型，并返回结构化响应。
• generate_text 函数使用 @traceable 装饰，每次调用都会作为追踪记录到 LangSmith（默认使用函数名作为追踪名称）。
• 自定义标签（aws-bedrock、langsmith、integration-test）和元数据（环境、模型信息）会传入装饰器，并附加到追踪记录，以便在 LangSmith UI 中筛选。
• 运行此代码时（设置了 LANGSMITH_TRACING=true 和 API key），LangSmith 会自动捕获输入提示词、模型输出、token 使用量和延迟。

在 LangSmith 中查看追踪

运行代码后，请前往 smith.langchain.com 中的 LangSmith 项目查看追踪。每条追踪包括：

• 请求详情：输入消息、模型参数和配置
• 响应详情：模型输出、token 使用量和响应元数据
• 性能指标：延迟、每秒 token 数和成本估算
• 自定义元数据：你提供给 @traceable 装饰器的标签和元数据

你可以按标签（例如 aws-bedrock 或 integration-test）筛选追踪，按元数据字段搜索，或深入查看特定追踪以调试问题。

后续步骤

• 进一步了解 LangSmith 功能，包括评估、数据集和反馈
• 探索 Bedrock 模型能力，例如工具调用、流式传输和提示词缓存
• 查看 LangChain Bedrock 集成文档，了解扩展思考和引用等高级功能

---