TensorZero 数据集与数据点编程指南用 Python 客户端与 curl 实现 Datasets Datapoints 的创建、读取与删除【免费下载链接】tensorzeroTensorZero is an open-source LLMOps platform that unifies an LLM gateway, observability, evaluation, optimization, and experimentation.项目地址: https://gitcode.com/GitHub_Trending/te/tensorzero本文以 TensorZero 仓库中的官方示例 examples/guides/datasets-datapoints 为主线系统讲解如何以编程方式管理数据集Dataset与数据点Datapoint。你将学会两种完全可运行的实操路径基于tensorzeroPython 客户端的方法调用以及基于 curl 的纯 HTTP 调用并深入理解 Gateway 层的数据校验、软删除与分页等底层实现从而把数据集操作无缝接入自己的评估与优化工作流。一、数据集与数据点TensorZero 数据资产的基石在 TensorZero 中数据集Dataset是数据点的命名集合而每个数据点Datapoint归属于一个具体的函数function其字段随函数类型chat或json而异。从结构上看数据点与一次推理inference高度镜像都包含input输入、可选的output输出以及其他元数据如tags标签。数据集是评估evaluation与优化optimization如 GEPA、SFT、DICL等上层工作流的数据来源。你可以通过 TensorZero UI 手动管理也可以通过 TensorZero Gateway 提供的 HTTP 接口以编程方式管理详见仓库文档 docs/gateway/api-reference/datasets-datapoints.mdx。本文聚焦后者给出可直接复制运行的完整示例。二、示例项目结构与环境准备示例位于 examples/guides/datasets-datapoints目录结构如下examples/guides/datasets-datapoints/ ├── config/ │ ├── functions/ │ │ └── extract_recipient/ │ │ └── output_schema.json # json 函数的输出 JSON Schema │ └── tensorzero.toml # Gateway 配置 ├── README.md # 官方指南 ├── docker-compose.yml # 一键启动 Postgres Gateway UI ├── main.py # Python 客户端示例 ├── main.sh # curl HTTP 示例 ├── pyproject.toml # Python 依赖tensorzero2025.5.7 └── uv.lock2.1 前置准备按官方指南 README.md 的步骤操作安装 Docker在 OpenAI 平台生成 API KeyOPENAI_API_KEY将OPENAI_API_KEY设为环境变量在示例目录下启动 TensorZero 与 Postgresdocker compose up2.2 一键启动的 compose 拓扑docker-compose.yml 编排了 4 个服务构成一个完整的本地开发环境服务镜像作用postgrestensorzero/postgres:17持久化数据集与推理数据暴露5432端口带健康检查gateway-run-postgres-migrationstensorzero/gateway在 Gateway 启动前执行--run-postgres-migrations完成数据库迁移service_completed_successfully后退出gatewaytensorzero/gateway主服务挂载./config到容器/app/config:ro通过--config-file /app/config/tensorzero.toml加载配置暴露3000端口uitensorzero/ui可视化界面通过TENSORZERO_GATEWAY_URL连接 Gateway暴露4000端口其中 Gateway 服务通过环境变量注入数据库连接与模型凭据environment: TENSORZERO_POSTGRES_URL: postgres://postgres:postgrespostgres:5432/tensorzero OPENAI_API_KEY: ${OPENAI_API_KEY:?Environment variable OPENAI_API_KEY must be set.}OPENAI_API_KEY使用了${VAR:?}语法强制校验未设置时 compose 会直接报错避免带着空凭据启动。2.3 示例函数配置config/tensorzero.toml 定义了本次示例用到的两个函数[functions.extract_recipient] type json output_schema functions/extract_recipient/output_schema.json [functions.extract_recipient.variants.baseline] type chat_completion model openai::gpt-4o-mini json_mode strict [functions.draft_email] type chat [functions.draft_email.variants.baseline] type chat_completion model openai::gpt-4o-miniextract_recipientjson类型函数输出受 output_schema.json 约束name与email两个必填字符串字段且additionalProperties: falsevariant 开启json_mode strictdraft_emailchat类型函数无结构化输出约束。这两个函数恰好对应数据点的两种类型json数据点与chat数据点示例将围绕它们构造数据。三、Python 客户端三种构造方式与四个核心操作Python 示例 main.py 演示了插入 → 按 ID 读取 → 删除 → 列表查询 → 清理的完整生命周期。下面按步骤拆解。3.1 三种数据点构造方式方式一直接使用字典dict结构天然与 HTTP JSON 一致extract_recipient_datapoint { function_name: extract_recipient, input: { messages: [ { role: user, content: [ { type: text, text: Please send this to Alice at aliceexample.com, } ], } ] }, }方式二使用JsonDatapointInsert类型可附加output与name等元数据extract_recipient_datapoint_with_output JsonDatapointInsert( function_nameextract_recipient, input{ messages: [ { role: user, content: [ { type: text, text: Please send this to Bob at bobexample.com, } ], } ] }, output{ name: Bob, email: bobexample.com, }, namebob_recipient_example, )方式三使用ChatDatapointInsert类型可附加tags标签draft_email_datapoint ChatDatapointInsert( function_namedraft_email, input{ messages: [ { role: user, content: [ { type: text, text: Please draft an email to Bob at bobexample.com, } ], } ] }, tags{ customer_id: 123, }, )兼容性说明本示例基于早期发布版本的 Python 客户端编写构造参数名与当前仓库中的客户端签名略有差异——当前 tensorzero.pyi 中create_datapoints的参数名为requests、delete_datapoints支持批量删除详见第 3.3 节。示例代码本身与仓库锁定的客户端版本pyproject.toml中tensorzero2025.5.7且exclude-newer3 天保持一致可直接运行底层 HTTP 契约不受影响。3.2 核心操作插入、读取、删除、列表在上下文管理器with TensorZeroGateway.build_http(gateway_urlhttp://localhost:3000) as t0:中所有调用都指向本地 Gateway3000端口with TensorZeroGateway.build_http( gateway_urlhttp://localhost:3000, ) as t0: # 1. 批量插入一次创建 3 个数据点 create_datapoints_response t0.create_datapoints( dataset_nameemail_application, datapoints[ extract_recipient_datapoint, extract_recipient_datapoint_with_output, draft_email_datapoint, ], ) print(create_datapoints_response) # 2. 按 ID 读取单个数据点返回列表中的第一个 ID get_datapoints_response t0.get_datapoints( dataset_nameemail_application, ids[create_datapoints_response[0]], ) print(get_datapoints_response) # 3. 删除单个数据点 t0.delete_datapoint( dataset_nameemail_application, datapoint_idcreate_datapoints_response[0], ) # 4. 列表查询查看剩余数据点 list_datapoints_response t0.list_datapoints(dataset_nameemail_application) print(list_datapoints_response) # 5. 清理删除剩余数据点 for datapoint in list_datapoints_response: t0.delete_datapoint( dataset_nameemail_application, datapoint_iddatapoint.id, )执行方式需已安装 uvuv run main.py关键语义create_datapoints返回idsUUIDv7 列表示例用create_datapoints_response[0]拿到第一个新数据点的 IDget_datapoints返回完整数据点对象含input、output、tags等字段delete_datapoint为软删除返回值为空示例打印N/Alist_datapoints返回数据点对象列表可用datapoint.id逐一清理若目标数据集不存在插入时会自动按给定名称创建数据集。3.3 当前仓库中客户端方法的签名仓库内 tensorzero.pyi 给出了 Python 客户端当前的完整方法签名第 707819 行可作为升级到新版客户端后的对照list_datapoints(*, dataset_name: str, request: ListDatapointsRequest) - GetDatapointsResponse支持分页与过滤参数create_datapoints(*, dataset_name: str, requests: Sequence[CreateDatapointRequest]) - CreateDatapointsResponse返回新建数据点 ID 列表get_datapoints(*, dataset_name: str | None ..., ids: Sequence[str]) - GetDatapointsResponse按 ID 读取。注释特别说明传入dataset_name能提升查询性能因为数据集是排序键sorting key的一部分delete_datapoints(*, dataset_name: str, ids: Sequence[str]) - DeleteDatapointsResponse批量删除另有update_datapoints、update_datapoints_metadata、delete_dataset、create_datapoints_from_inferences等进阶方法见第六节。四、curl 纯 HTTP 方式四个端点的完整调用链不依赖任何 SDK 时可直接用 curl 操作。bash 脚本 main.sh 演示了完整流程先把 3 个数据点写入临时 JSON 文件再依次调用插入、按 ID 读取、删除、列表、清理共 5 组请求。4.1 请求体三种数据点的 JSON 形态脚本用 heredoc 构造请求体并写入mktemp创建的临时文件通过type字段区分数据点类型{ datapoints: [ { type: json, function_name: extract_recipient, input: { messages: [ { role: user, content: [ { type: text, text: Please send this to Alice at aliceexample.com } ] } ] } }, { type: json, function_name: extract_recipient, input: { messages: [ { role: user, content: [ { type: text, text: Please send this to Bob at bobexample.com } ] } ] }, output: { name: Bob, email: bobexample.com } }, { type: chat, function_name: draft_email, input: { messages: [ { role: user, content: [ { type: text, text: Please draft an email to Bob at bobexample.com } ] } ] }, tags: { customer_id: 123 } } ] }4.2 四个核心端点的调用① 批量插入POST /v1/datasets/{dataset_name}/datapointscurl -s -X POST \ http://localhost:3000/v1/datasets/email_application/datapoints \ -H Content-Type: application/json \ -d $TEMP_FILE响应为{ids: [UUIDv7, ...]}。脚本用jq -e .ids | type array校验响应格式并用jq -r .ids[0]提取第一个 ID 供后续步骤使用校验失败则报错退出——这是生产脚本中值得借鉴的健壮性写法。② 按 ID 读取POST /v1/datasets/{dataset_name}/get_datapointscurl -s -X POST \ http://localhost:3000/v1/datasets/email_application/get_datapoints \ -H Content-Type: application/json \ -d {\ids\: [\${FIRST_DATAPOINT_ID}\]}③ 删除DELETE /v1/datasets/{dataset_name}/datapointscurl -s -X DELETE \ http://localhost:3000/v1/datasets/email_application/datapoints \ -H Content-Type: application/json \ -d {\ids\: [\${FIRST_DATAPOINT_ID}\]}④ 列表查询POST /v1/datasets/{dataset_name}/list_datapointscurl -s -X POST \ http://localhost:3000/v1/datasets/email_application/list_datapoints \ -H Content-Type: application/json \ -d {}⑤ 清理脚本把列表响应的[.datapoints[].id]收集为 JSON 数组若不为空则再一次DELETE批量删除全部剩余数据点最后删除临时文件。运行方式./main.sh4.3 HTTP 端点速查表以下端点均在 crates/gateway/src/routes/external.rs 中注册方法路径请求体要点响应POST/v1/datasets/{dataset_name}/datapointsdatapoints列表每项含typechat/json与function_name{ids: [...]}UUIDv7POST/v1/datasets/{dataset_name}/get_datapoints{ids: [...]}{datapoints: [...]}POST/v1/datasets/{dataset_name}/list_datapoints可选function_name、limit、offset、filter、order_by等{datapoints: [...]}DELETE/v1/datasets/{dataset_name}/datapoints{ids: [...]}{num_deleted_datapoints: N}注仓库还保留了一个不带数据集名的旧版读取端点POST /v1/datasets/get_datapoints并在 get_datapoints.rs 中打印弃用警告建议改用带数据集名的版本以获得更好的查询性能。五、Gateway 侧实现原理从 HTTP 到数据库理解底层实现有助于排查问题与预估性能。以下均可在仓库源码中找到对应实现。5.1 创建数据点校验与并行入库create_datapoints.rs 中的核心逻辑create_datapoints依次执行validate_dataset_name(dataset_name)校验数据集名称合法性空列表校验request.datapoints.is_empty()时直接返回InvalidRequest错误At least one datapoint must be provided将CreateDatapointRequestChat或Json两种变体逐个转换为数据库插入结构并通过futures::future::try_join_all并行完成因为可能需要存储输入内容任一失败则整体回滚入库后返回CreateDatapointsResponse { ids: VecUuid }。请求类型定义见 types.rsCreateDatapointRequest是带type标签的枚举chat/json。其中json数据点支持动态传入output_schema未提供时使用函数配置的输出 Schema提供时会被校验chat数据点则支持allowed_tools、tool_choice、parallel_tool_calls、episode_id等与推理请求一致的字段。5.2 列表查询默认分页与高级过滤get_datapoints.rs 定义了列表接口的三个默认值const DEFAULT_LIMIT: u32 20; const DEFAULT_OFFSET: u32 0; const DEFAULT_ALLOW_STALE: bool false;对应 types.rs 中ListDatapointsRequest的可选参数function_name仅返回指定函数的数据点limit/page_size每页数量默认 20page_size已标记弃用自 2025.11.1 起请用limitoffset跳过数量默认 0filter按标签、时间以及 AND/OR/NOT 逻辑组合过滤order_by排序条件列表如按timestamp、search_relevancesearch_query_experimental实验性全文搜索——大小写不敏感的精确子串匹配不分词、不做相关性打分无其他过滤条件时可能全表扫描数据量大时可能极慢官方明确不建议在关键场景依赖。5.3 软删除语义删除操作delete_datapoints与delete_dataset执行的是软删除数据点被标记为 stale过期之后列表查询、评估运行等都会忽略它们但原始数据仍保留在数据库中。官方 API 文档docs/gateway/api-reference/datasets-datapoints.mdx特别提示按 ID 直接读取get_datapoints时stale 数据点仍会出现在响应中。这意味着删除后立刻按 ID 读取数据依然可见属于预期行为。六、进阶操作更新与从推理生成数据点除了增删查列四个基础操作同一份 API 参考还提供了几个高频进阶能力适合在生产工作流中使用从推理创建数据点POST /v1/datasets/{dataset_name}/from_inferences客户端方法create_datapoints_from_inferences通过type字段选择inference_ids按推理 ID 列表output_source可指定inference/demonstration/none默认inference或inference_query复用推理列表查询参数两种模式将历史推理沉淀为可复用数据集——这是构建持续优化闭环的关键路径更新数据点PATCH /v1/datasets/{dataset_name}/datapointsupdate_datapoints创建新版本——原数据点被标记为 stale软删除新数据点获得新 ID省略字段保持不变显式传null清空可空字段更新数据点元数据PATCH /v1/datasets/{dataset_name}/datapoints/metadataupdate_datapoints_metadata仅原地更新name等元数据不产生新版本、不改变 ID删除整个数据集DELETE /v1/datasets/{dataset_name}delete_dataset软删除数据集下所有数据点返回num_deleted_datapoints。七、测试验证仓库中的自动化佐证仓库为这套 API 提供了完整的自动化测试见 crates/tensorzero-python/tests/test_datapoints_v1.py同步与异步客户端均有覆盖按 ID 读取含传入/不传dataset_name两种形态列表查询的分页与过滤limit/offset组合批量删除与整数据集删除更新元数据后按 ID 读取验证结果从推理创建数据点create_datapoints_from_inferences边界情况空 ID 列表返回空、不存在的 ID 返回空列表。在 Rust 侧Gateway 的端到端测试同样覆盖数据点流程如 crates/tensorzero-core/tests/e2e/endpoints/datasets/mod.rs 与 MCP 场景下的create_datapoints测试。若你在修改或调试相关功能这些测试是现成的行为基准。结语从docker compose up到uv run main.py或./main.sh本文完整复现了 TensorZero 数据集与数据点的编程管理闭环三种数据点构造方式、四个核心 HTTP 端点、Gateway 侧的校验与并行入库、默认分页与软删除语义以及从推理生成数据点等进阶能力。无论你是要搭建评估基准、准备微调数据还是构建推理 → 沉淀数据集 → 优化的自动闭环这套 API 都是直接可用的基础能力。【免费下载链接】tensorzeroTensorZero is an open-source LLMOps platform that unifies an LLM gateway, observability, evaluation, optimization, and experimentation.项目地址: https://gitcode.com/GitHub_Trending/te/tensorzero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
TensorZero 数据集与数据点编程指南：用 Python 客户端与 curl 实现 Datasets Datapoints 的创建、读取与删除
TensorZero 数据集与数据点编程指南用 Python 客户端与 curl 实现 Datasets Datapoints 的创建、读取与删除【免费下载链接】tensorzeroTensorZero is an open-source LLMOps platform that unifies an LLM gateway, observability, evaluation, optimization, and experimentation.项目地址: https://gitcode.com/GitHub_Trending/te/tensorzero本文以 TensorZero 仓库中的官方示例 examples/guides/datasets-datapoints 为主线系统讲解如何以编程方式管理数据集Dataset与数据点Datapoint。你将学会两种完全可运行的实操路径基于tensorzeroPython 客户端的方法调用以及基于 curl 的纯 HTTP 调用并深入理解 Gateway 层的数据校验、软删除与分页等底层实现从而把数据集操作无缝接入自己的评估与优化工作流。一、数据集与数据点TensorZero 数据资产的基石在 TensorZero 中数据集Dataset是数据点的命名集合而每个数据点Datapoint归属于一个具体的函数function其字段随函数类型chat或json而异。从结构上看数据点与一次推理inference高度镜像都包含input输入、可选的output输出以及其他元数据如tags标签。数据集是评估evaluation与优化optimization如 GEPA、SFT、DICL等上层工作流的数据来源。你可以通过 TensorZero UI 手动管理也可以通过 TensorZero Gateway 提供的 HTTP 接口以编程方式管理详见仓库文档 docs/gateway/api-reference/datasets-datapoints.mdx。本文聚焦后者给出可直接复制运行的完整示例。二、示例项目结构与环境准备示例位于 examples/guides/datasets-datapoints目录结构如下examples/guides/datasets-datapoints/ ├── config/ │ ├── functions/ │ │ └── extract_recipient/ │ │ └── output_schema.json # json 函数的输出 JSON Schema │ └── tensorzero.toml # Gateway 配置 ├── README.md # 官方指南 ├── docker-compose.yml # 一键启动 Postgres Gateway UI ├── main.py # Python 客户端示例 ├── main.sh # curl HTTP 示例 ├── pyproject.toml # Python 依赖tensorzero2025.5.7 └── uv.lock2.1 前置准备按官方指南 README.md 的步骤操作安装 Docker在 OpenAI 平台生成 API KeyOPENAI_API_KEY将OPENAI_API_KEY设为环境变量在示例目录下启动 TensorZero 与 Postgresdocker compose up2.2 一键启动的 compose 拓扑docker-compose.yml 编排了 4 个服务构成一个完整的本地开发环境服务镜像作用postgrestensorzero/postgres:17持久化数据集与推理数据暴露5432端口带健康检查gateway-run-postgres-migrationstensorzero/gateway在 Gateway 启动前执行--run-postgres-migrations完成数据库迁移service_completed_successfully后退出gatewaytensorzero/gateway主服务挂载./config到容器/app/config:ro通过--config-file /app/config/tensorzero.toml加载配置暴露3000端口uitensorzero/ui可视化界面通过TENSORZERO_GATEWAY_URL连接 Gateway暴露4000端口其中 Gateway 服务通过环境变量注入数据库连接与模型凭据environment: TENSORZERO_POSTGRES_URL: postgres://postgres:postgrespostgres:5432/tensorzero OPENAI_API_KEY: ${OPENAI_API_KEY:?Environment variable OPENAI_API_KEY must be set.}OPENAI_API_KEY使用了${VAR:?}语法强制校验未设置时 compose 会直接报错避免带着空凭据启动。2.3 示例函数配置config/tensorzero.toml 定义了本次示例用到的两个函数[functions.extract_recipient] type json output_schema functions/extract_recipient/output_schema.json [functions.extract_recipient.variants.baseline] type chat_completion model openai::gpt-4o-mini json_mode strict [functions.draft_email] type chat [functions.draft_email.variants.baseline] type chat_completion model openai::gpt-4o-miniextract_recipientjson类型函数输出受 output_schema.json 约束name与email两个必填字符串字段且additionalProperties: falsevariant 开启json_mode strictdraft_emailchat类型函数无结构化输出约束。这两个函数恰好对应数据点的两种类型json数据点与chat数据点示例将围绕它们构造数据。三、Python 客户端三种构造方式与四个核心操作Python 示例 main.py 演示了插入 → 按 ID 读取 → 删除 → 列表查询 → 清理的完整生命周期。下面按步骤拆解。3.1 三种数据点构造方式方式一直接使用字典dict结构天然与 HTTP JSON 一致extract_recipient_datapoint { function_name: extract_recipient, input: { messages: [ { role: user, content: [ { type: text, text: Please send this to Alice at aliceexample.com, } ], } ] }, }方式二使用JsonDatapointInsert类型可附加output与name等元数据extract_recipient_datapoint_with_output JsonDatapointInsert( function_nameextract_recipient, input{ messages: [ { role: user, content: [ { type: text, text: Please send this to Bob at bobexample.com, } ], } ] }, output{ name: Bob, email: bobexample.com, }, namebob_recipient_example, )方式三使用ChatDatapointInsert类型可附加tags标签draft_email_datapoint ChatDatapointInsert( function_namedraft_email, input{ messages: [ { role: user, content: [ { type: text, text: Please draft an email to Bob at bobexample.com, } ], } ] }, tags{ customer_id: 123, }, )兼容性说明本示例基于早期发布版本的 Python 客户端编写构造参数名与当前仓库中的客户端签名略有差异——当前 tensorzero.pyi 中create_datapoints的参数名为requests、delete_datapoints支持批量删除详见第 3.3 节。示例代码本身与仓库锁定的客户端版本pyproject.toml中tensorzero2025.5.7且exclude-newer3 天保持一致可直接运行底层 HTTP 契约不受影响。3.2 核心操作插入、读取、删除、列表在上下文管理器with TensorZeroGateway.build_http(gateway_urlhttp://localhost:3000) as t0:中所有调用都指向本地 Gateway3000端口with TensorZeroGateway.build_http( gateway_urlhttp://localhost:3000, ) as t0: # 1. 批量插入一次创建 3 个数据点 create_datapoints_response t0.create_datapoints( dataset_nameemail_application, datapoints[ extract_recipient_datapoint, extract_recipient_datapoint_with_output, draft_email_datapoint, ], ) print(create_datapoints_response) # 2. 按 ID 读取单个数据点返回列表中的第一个 ID get_datapoints_response t0.get_datapoints( dataset_nameemail_application, ids[create_datapoints_response[0]], ) print(get_datapoints_response) # 3. 删除单个数据点 t0.delete_datapoint( dataset_nameemail_application, datapoint_idcreate_datapoints_response[0], ) # 4. 列表查询查看剩余数据点 list_datapoints_response t0.list_datapoints(dataset_nameemail_application) print(list_datapoints_response) # 5. 清理删除剩余数据点 for datapoint in list_datapoints_response: t0.delete_datapoint( dataset_nameemail_application, datapoint_iddatapoint.id, )执行方式需已安装 uvuv run main.py关键语义create_datapoints返回idsUUIDv7 列表示例用create_datapoints_response[0]拿到第一个新数据点的 IDget_datapoints返回完整数据点对象含input、output、tags等字段delete_datapoint为软删除返回值为空示例打印N/Alist_datapoints返回数据点对象列表可用datapoint.id逐一清理若目标数据集不存在插入时会自动按给定名称创建数据集。3.3 当前仓库中客户端方法的签名仓库内 tensorzero.pyi 给出了 Python 客户端当前的完整方法签名第 707819 行可作为升级到新版客户端后的对照list_datapoints(*, dataset_name: str, request: ListDatapointsRequest) - GetDatapointsResponse支持分页与过滤参数create_datapoints(*, dataset_name: str, requests: Sequence[CreateDatapointRequest]) - CreateDatapointsResponse返回新建数据点 ID 列表get_datapoints(*, dataset_name: str | None ..., ids: Sequence[str]) - GetDatapointsResponse按 ID 读取。注释特别说明传入dataset_name能提升查询性能因为数据集是排序键sorting key的一部分delete_datapoints(*, dataset_name: str, ids: Sequence[str]) - DeleteDatapointsResponse批量删除另有update_datapoints、update_datapoints_metadata、delete_dataset、create_datapoints_from_inferences等进阶方法见第六节。四、curl 纯 HTTP 方式四个端点的完整调用链不依赖任何 SDK 时可直接用 curl 操作。bash 脚本 main.sh 演示了完整流程先把 3 个数据点写入临时 JSON 文件再依次调用插入、按 ID 读取、删除、列表、清理共 5 组请求。4.1 请求体三种数据点的 JSON 形态脚本用 heredoc 构造请求体并写入mktemp创建的临时文件通过type字段区分数据点类型{ datapoints: [ { type: json, function_name: extract_recipient, input: { messages: [ { role: user, content: [ { type: text, text: Please send this to Alice at aliceexample.com } ] } ] } }, { type: json, function_name: extract_recipient, input: { messages: [ { role: user, content: [ { type: text, text: Please send this to Bob at bobexample.com } ] } ] }, output: { name: Bob, email: bobexample.com } }, { type: chat, function_name: draft_email, input: { messages: [ { role: user, content: [ { type: text, text: Please draft an email to Bob at bobexample.com } ] } ] }, tags: { customer_id: 123 } } ] }4.2 四个核心端点的调用① 批量插入POST /v1/datasets/{dataset_name}/datapointscurl -s -X POST \ http://localhost:3000/v1/datasets/email_application/datapoints \ -H Content-Type: application/json \ -d $TEMP_FILE响应为{ids: [UUIDv7, ...]}。脚本用jq -e .ids | type array校验响应格式并用jq -r .ids[0]提取第一个 ID 供后续步骤使用校验失败则报错退出——这是生产脚本中值得借鉴的健壮性写法。② 按 ID 读取POST /v1/datasets/{dataset_name}/get_datapointscurl -s -X POST \ http://localhost:3000/v1/datasets/email_application/get_datapoints \ -H Content-Type: application/json \ -d {\ids\: [\${FIRST_DATAPOINT_ID}\]}③ 删除DELETE /v1/datasets/{dataset_name}/datapointscurl -s -X DELETE \ http://localhost:3000/v1/datasets/email_application/datapoints \ -H Content-Type: application/json \ -d {\ids\: [\${FIRST_DATAPOINT_ID}\]}④ 列表查询POST /v1/datasets/{dataset_name}/list_datapointscurl -s -X POST \ http://localhost:3000/v1/datasets/email_application/list_datapoints \ -H Content-Type: application/json \ -d {}⑤ 清理脚本把列表响应的[.datapoints[].id]收集为 JSON 数组若不为空则再一次DELETE批量删除全部剩余数据点最后删除临时文件。运行方式./main.sh4.3 HTTP 端点速查表以下端点均在 crates/gateway/src/routes/external.rs 中注册方法路径请求体要点响应POST/v1/datasets/{dataset_name}/datapointsdatapoints列表每项含typechat/json与function_name{ids: [...]}UUIDv7POST/v1/datasets/{dataset_name}/get_datapoints{ids: [...]}{datapoints: [...]}POST/v1/datasets/{dataset_name}/list_datapoints可选function_name、limit、offset、filter、order_by等{datapoints: [...]}DELETE/v1/datasets/{dataset_name}/datapoints{ids: [...]}{num_deleted_datapoints: N}注仓库还保留了一个不带数据集名的旧版读取端点POST /v1/datasets/get_datapoints并在 get_datapoints.rs 中打印弃用警告建议改用带数据集名的版本以获得更好的查询性能。五、Gateway 侧实现原理从 HTTP 到数据库理解底层实现有助于排查问题与预估性能。以下均可在仓库源码中找到对应实现。5.1 创建数据点校验与并行入库create_datapoints.rs 中的核心逻辑create_datapoints依次执行validate_dataset_name(dataset_name)校验数据集名称合法性空列表校验request.datapoints.is_empty()时直接返回InvalidRequest错误At least one datapoint must be provided将CreateDatapointRequestChat或Json两种变体逐个转换为数据库插入结构并通过futures::future::try_join_all并行完成因为可能需要存储输入内容任一失败则整体回滚入库后返回CreateDatapointsResponse { ids: VecUuid }。请求类型定义见 types.rsCreateDatapointRequest是带type标签的枚举chat/json。其中json数据点支持动态传入output_schema未提供时使用函数配置的输出 Schema提供时会被校验chat数据点则支持allowed_tools、tool_choice、parallel_tool_calls、episode_id等与推理请求一致的字段。5.2 列表查询默认分页与高级过滤get_datapoints.rs 定义了列表接口的三个默认值const DEFAULT_LIMIT: u32 20; const DEFAULT_OFFSET: u32 0; const DEFAULT_ALLOW_STALE: bool false;对应 types.rs 中ListDatapointsRequest的可选参数function_name仅返回指定函数的数据点limit/page_size每页数量默认 20page_size已标记弃用自 2025.11.1 起请用limitoffset跳过数量默认 0filter按标签、时间以及 AND/OR/NOT 逻辑组合过滤order_by排序条件列表如按timestamp、search_relevancesearch_query_experimental实验性全文搜索——大小写不敏感的精确子串匹配不分词、不做相关性打分无其他过滤条件时可能全表扫描数据量大时可能极慢官方明确不建议在关键场景依赖。5.3 软删除语义删除操作delete_datapoints与delete_dataset执行的是软删除数据点被标记为 stale过期之后列表查询、评估运行等都会忽略它们但原始数据仍保留在数据库中。官方 API 文档docs/gateway/api-reference/datasets-datapoints.mdx特别提示按 ID 直接读取get_datapoints时stale 数据点仍会出现在响应中。这意味着删除后立刻按 ID 读取数据依然可见属于预期行为。六、进阶操作更新与从推理生成数据点除了增删查列四个基础操作同一份 API 参考还提供了几个高频进阶能力适合在生产工作流中使用从推理创建数据点POST /v1/datasets/{dataset_name}/from_inferences客户端方法create_datapoints_from_inferences通过type字段选择inference_ids按推理 ID 列表output_source可指定inference/demonstration/none默认inference或inference_query复用推理列表查询参数两种模式将历史推理沉淀为可复用数据集——这是构建持续优化闭环的关键路径更新数据点PATCH /v1/datasets/{dataset_name}/datapointsupdate_datapoints创建新版本——原数据点被标记为 stale软删除新数据点获得新 ID省略字段保持不变显式传null清空可空字段更新数据点元数据PATCH /v1/datasets/{dataset_name}/datapoints/metadataupdate_datapoints_metadata仅原地更新name等元数据不产生新版本、不改变 ID删除整个数据集DELETE /v1/datasets/{dataset_name}delete_dataset软删除数据集下所有数据点返回num_deleted_datapoints。七、测试验证仓库中的自动化佐证仓库为这套 API 提供了完整的自动化测试见 crates/tensorzero-python/tests/test_datapoints_v1.py同步与异步客户端均有覆盖按 ID 读取含传入/不传dataset_name两种形态列表查询的分页与过滤limit/offset组合批量删除与整数据集删除更新元数据后按 ID 读取验证结果从推理创建数据点create_datapoints_from_inferences边界情况空 ID 列表返回空、不存在的 ID 返回空列表。在 Rust 侧Gateway 的端到端测试同样覆盖数据点流程如 crates/tensorzero-core/tests/e2e/endpoints/datasets/mod.rs 与 MCP 场景下的create_datapoints测试。若你在修改或调试相关功能这些测试是现成的行为基准。结语从docker compose up到uv run main.py或./main.sh本文完整复现了 TensorZero 数据集与数据点的编程管理闭环三种数据点构造方式、四个核心 HTTP 端点、Gateway 侧的校验与并行入库、默认分页与软删除语义以及从推理生成数据点等进阶能力。无论你是要搭建评估基准、准备微调数据还是构建推理 → 沉淀数据集 → 优化的自动闭环这套 API 都是直接可用的基础能力。【免费下载链接】tensorzeroTensorZero is an open-source LLMOps platform that unifies an LLM gateway, observability, evaluation, optimization, and experimentation.项目地址: https://gitcode.com/GitHub_Trending/te/tensorzero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考