随追踪上传文件

当你使用 @traceable 装饰器或 traceable 包装器进行追踪时，LangSmith 支持随追踪一起上传二进制文件（如图片、音频、视频、PDF 和 CSV）。这在处理使用多模态输入或输出的 LLM 流水线时尤其有用。

在 Python 和 TypeScript SDK 中，你都可以通过指定每个文件的 MIME 类型和二进制内容来向追踪添加附件。本页说明如何在 Python 中使用 Attachment 类型、在 TypeScript 中使用 Uint8Array / ArrayBuffer 来定义和追踪附件。

Python

在 Python SDK 中，你可以使用 Attachment 类型向追踪添加文件。每个 Attachment 需要：

• mime_type（str）：文件的 MIME 类型（例如 "image/png"）。
• data（bytes | Path）：文件的二进制内容，或文件路径。

为方便起见，你也可以用 (mime_type, data) 形式的元组来定义附件。

提供文件数据有两种方式：

• 自行加载字节并直接传入（适用于所有环境），或
• 传入 Path 对象，并在 @traceable 装饰器上设置 dangerously_allow_filesystem=True，让 SDK 读取该文件。

NOTE

dangerously_allow_filesystem 标志是面向服务器和多租户环境的安全保障，因为这些环境中用户可控的输入可能影响文件路径。在可信任环境中（你拥有文件路径的本地脚本或受控流水线），启用它是安全的。

用 @traceable 装饰函数，并将 Attachment 实例作为参数传入。以下示例演示了两种方式：手动将文件字节加载到 Attachment，以及传入 Path 对象并设置 dangerously_allow_filesystem=True：

from langsmith import traceable
from langsmith.schemas import Attachment
from pathlib import Path
import os

# Must set dangerously_allow_filesystem to True if you want to use file paths
@traceable(dangerously_allow_filesystem=True)
def trace_with_attachments(
    val: int,
    text: str,
    image: Attachment,
    audio: Attachment,
    video: Attachment,
    pdf: Attachment,
    csv: Attachment,
):
    return f"Processed: {val}, {text}, {len(image.data)}, {len(audio.data)}, {len(video.data)}, {len(pdf.data), {len(csv.data)}}"

# Helper function to load files as bytes
def load_file(file_path: str) -> bytes:
    with open(file_path, "rb") as f:
        return f.read()

# Load files and create attachments
image_data = load_file("my_image.png")
audio_data = load_file("my_mp3.mp3")
video_data = load_file("my_video.mp4")
pdf_data = load_file("my_document.pdf")

image_attachment = Attachment(mime_type="image/png", data=image_data)
audio_attachment = Attachment(mime_type="audio/mpeg", data=audio_data)
video_attachment = Attachment(mime_type="video/mp4", data=video_data)
pdf_attachment = ("application/pdf", pdf_data) # Can just define as tuple of (mime_type, data)
csv_attachment = Attachment(mime_type="text/csv", data=Path(os.getcwd()) / "my_csv.csv")

# Define other parameters
val = 42
text = "Hello, world!"

# Call the function with traced attachments
result = trace_with_attachments(
    val=val,
    text=text,
    image=image_attachment,
    audio=audio_attachment,
    video=video_attachment,
    pdf=pdf_attachment,
    csv=csv_attachment,
)

TypeScript

在 TypeScript SDK 中，你可以使用 Uint8Array 或 ArrayBuffer 作为数据类型来向追踪添加附件。每个附件的 MIME 类型在 extractAttachments 中指定：

• Uint8Array：适合直接处理二进制数据。
• ArrayBuffer：表示固定长度的二进制数据，你可以按需将其转换为 Uint8Array。

在 TypeScript SDK 中，extractAttachments 函数是 traceable 配置的可选参数。当调用被 traceable 包装的函数时，它会从输入中提取二进制数据（例如图片、音频文件），指定其 MIME 类型，并与其他追踪数据一起记录。

NOTE

在 TypeScript SDK 中不能直接传入文件路径，因为并非所有运行时环境都支持访问本地文件。

用 traceable 包装函数，并在 extractAttachments 选项中包含附件。签名如下：

type AttachmentData = Uint8Array | ArrayBuffer;
type Attachments = Record<string, [string, AttachmentData]>;

extractAttachments?: (
    ...args: Parameters<Func>
) => [Attachments | undefined, KVMap];

以下示例展示了完整实现：

import { traceable } from "langsmith/traceable";

const traceableWithAttachments = traceable(
    (
        val: number,
        text: string,
        attachment: Uint8Array,
        attachment2: ArrayBuffer,
        attachment3: Uint8Array,
        attachment4: ArrayBuffer,
        attachment5: Uint8Array,
    ) =>
        `Processed: ${val}, ${text}, ${attachment.length}, ${attachment2.byteLength}, ${attachment3.length}, ${attachment4.byteLength}, ${attachment5.byteLength}`,
    {
        name: "traceWithAttachments",
        extractAttachments: (
            val: number,
            text: string,
            attachment: Uint8Array,
            attachment2: ArrayBuffer,
            attachment3: Uint8Array,
            attachment4: ArrayBuffer,
            attachment5: Uint8Array,
        ) => [
            {
                "image inputs": ["image/png", attachment],
                "mp3 inputs": ["audio/mpeg", new Uint8Array(attachment2)],
                "video inputs": ["video/mp4", attachment3],
                "pdf inputs": ["application/pdf", new Uint8Array(attachment4)],
                "csv inputs": ["text/csv", new Uint8Array(attachment5)],
            },
            { val, text },
        ],
    }
);

const fs = Deno // or Node.js fs module
const image = await fs.readFile("my_image.png"); // Uint8Array
const mp3Buffer = await fs.readFile("my_mp3.mp3");
const mp3ArrayBuffer = mp3Buffer.buffer; // Convert to ArrayBuffer
const video = await fs.readFile("my_video.mp4"); // Uint8Array
const pdfBuffer = await fs.readFile("my_document.pdf");
const pdfArrayBuffer = pdfBuffer.buffer; // Convert to ArrayBuffer
const csv = await fs.readFile("test-vals.csv"); // Uint8Array

// Define example parameters
const val = 42;
const text = "Hello, world!";

// Call traceableWithAttachments with the files
const result = await traceableWithAttachments(
    val, text, image, mp3ArrayBuffer, video, pdfArrayBuffer, csv
);

相关

• 管理数据集
• 设置 LLM-as-a-judge 在线评估器

---