数据模型

TensorZero网关将推理和反馈数据存储在ClickHouse中。这些数据可用于可观测性、实验和优化。

ChatInference

ChatInference 表存储了向TensorZero网关发出的聊天功能推理请求的相关信息。

一个ChatInference行可以关联一个或多个ModelInference行，具体取决于变体的type类型。 对于chat_completion类型，这两个表的行之间将是一对一的关系。 对于其他变体类型，则可能存在更多关联行。

列名	类型	备注
id	UUID	Must be a UUIDv7
function_name	String
variant_name	String
episode_id	UUID	Must be a UUIDv7
input	String (JSON)	input field in the /inference request body
output	String (JSON)	Array of content blocks
tool_params	String (JSON)	Object with any tool parameters (e.g. tool_choice, available_tools) used for the inference
inference_params	String (JSON)	Object with any inference parameters per variant type (e.g. {"chat_completion": {"temperature": 0.5}})
processing_time_ms	UInt32
timestamp	DateTime	Materialized from id (using UUIDv7ToDateTime function)
tags	Map(String, String)	User-assigned tags (e.g. {"user_id": "123"})

JsonInference

JsonInference 表存储了向 TensorZero 网关发起的 JSON 函数推理请求的相关信息。

一条JsonInference记录可以关联一条或多条ModelInference记录，具体取决于变体的type类型。 对于chat_completion类型，这两个表之间的记录将是一对一关系。 对于其他变体类型，则可能存在更多关联记录。

列名	类型	备注
id	UUID	Must be a UUIDv7
function_name	String
variant_name	String
episode_id	UUID	Must be a UUIDv7
input	String (JSON)	input field in the /inference request body
output	String (JSON)	Object with parsed and raw fields
output_schema	String (JSON)	Schema that the output must conform to
inference_params	String (JSON)	Object with any inference parameters per variant type (e.g. {"chat_completion": {"temperature": 0.5}})
processing_time_ms	UInt32
timestamp	DateTime	Materialized from id (using UUIDv7ToDateTime function)
tags	Map(String, String)	User-assigned tags (e.g. {"user_id": "123"})

ModelInference

ModelInference 表存储了每次向模型提供商发起推理请求的相关信息。这些信息相当于您直接调用模型提供商时发起的推理请求。

列名	类型	备注
id	UUID	Must be a UUIDv7
inference_id	UUID	Must be a UUIDv7
raw_request	String	Raw request as sent to the model provider (varies)
raw_response	String	Raw response from the model provider (varies)
model_name	String	Name of the model used for the inference
model_provider_name	String	Name of the model provider used for the inference
input_tokens	Nullable(UInt32)
output_tokens	Nullable(UInt32)
response_time_ms	Nullable(UInt32)
ttft_ms	Nullable(UInt32)	Only available in streaming inferences
timestamp	DateTime	Materialized from id (using UUIDv7ToDateTime function)
system	Nullable(String)	The system input to the model
input_messages	Array(RequestMessage)	The user and assistant messages input to the model
output	Array(ContentBlock)	The output of the model

RequestMessage是一个具有{role: "user" | "assistant", content: List[ContentBlock]}结构的对象（内容块定义见此处）。

DynamicInContextLearningExample

DynamicInContextLearningExample 表存储了动态上下文学习变体的示例。

列名	类型	备注
id	UUID	Must be a UUIDv7
function_name	String
variant_name	String
namespace	String
input	String (JSON)
output	String
embedding	Array(Float32)
timestamp	DateTime	Materialized from id (using UUIDv7ToDateTime function)

BooleanMetricFeedback

BooleanMetricFeedback 表存储了针对 type = "boolean" 类型指标的反馈数据。

列名	类型	备注
id	UUID	Must be a UUIDv7
target_id	UUID	Must be a UUIDv7 that is either inference_id or episode_id depending on level in metric config
metric_name	String
value	Bool
timestamp	DateTime	Materialized from id (using UUIDv7ToDateTime function)
tags	Map(String, String)	User-assigned tags (e.g. {"author": "Alice"})

FloatMetricFeedback

FloatMetricFeedback 表存储针对 type = "float" 类型指标的反馈数据。

列名	类型	备注
id	UUID	Must be a UUIDv7
target_id	UUID	Must be a UUIDv7 that is either inference_id or episode_id depending on level in metric config
metric_name	String
value	Float32
timestamp	DateTime	Materialized from id (using UUIDv7ToDateTime function)
tags	Map(String, String)	User-assigned tags (e.g. {"author": "Alice"})

CommentFeedback

CommentFeedback表存储了以"comment"作为metric_name提供的反馈。评论是自由格式的文本反馈。

列名	类型	备注
id	UUID	Must be a UUIDv7
target_id	UUID	Must be a UUIDv7 that is either inference_id or episode_id depending on level in metric config
target_type	"inference" or "episode"
value	String
timestamp	DateTime	Materialized from id (using UUIDv7ToDateTime function)
tags	Map(String, String)	User-assigned tags (e.g. {"author": "Alice"})

DemonstrationFeedback

DemonstrationFeedback 表以示范的形式存储反馈。示范是良好行为的示例。

列名	类型	备注
id	UUID	Must be a UUIDv7
inference_id	UUID	Must be a UUIDv7
value	String	The demonstration or example provided as feedback (must match function output)
timestamp	DateTime	Materialized from id (using UUIDv7ToDateTime function)
tags	Map(String, String)	User-assigned tags (e.g. {"author": "Alice"})

ModelInferenceCache

ModelInferenceCache 表存储缓存的模型推理结果，以避免重复请求。

列名	类型	备注
short_cache_key	UInt64	First part of composite key for fast lookups
long_cache_key	FixedString(64)	Hex-encoded 256-bit key for full cache validation
timestamp	DateTime	When this cache entry was created, defaults to now()
output	String	The cached model output
raw_request	String	Raw request that was sent to the model provider
raw_response	String	Raw response received from the model provider
is_deleted	Bool	Soft deletion flag, defaults to false

该表使用ReplacingMergeTree引擎，通过timestamp和is_deleted列实现去重功能。 数据按月分区，并按复合缓存键(short_cache_key, long_cache_key)排序。 其中short_cache_key作为主键以提升性能，同时在long_cache_key上建立的布隆过滤器索引有助于优化点查询效率。

ChatInferenceDataset

ChatInferenceDataset 表存储按数据集组织的聊天推理示例。

列名	类型	备注
dataset_name	LowCardinality(String)	Name of the dataset this example belongs to
function_name	LowCardinality(String)	Name of the function this example is for
id	UUID	Must be a UUIDv7, often the inference ID if generated from an inference
episode_id	UUID	Must be a UUIDv7
input	String (JSON)	input field in the /inference request body
output	Nullable(String) (JSON)	Array of content blocks
tool_params	String (JSON)	Object with any tool parameters (e.g. tool_choice, available_tools) used for the inference
tags	Map(String, String)	User-assigned tags (e.g. {"user_id": "123"})
auxiliary	String	Additional JSON data (unstructured)
is_deleted	Bool	Soft deletion flag, defaults to false
updated_at	DateTime	When this dataset entry was updated, defaults to now()

该表使用ReplacingMergeTree引擎，带有updated_at和is_deleted列用于去重。 表数据按dataset_name、function_name和id排序，以优化按数据集和函数筛选的查询性能。

JsonInferenceDataset

JsonInferenceDataset 表存储按数据集组织的JSON推理示例。

列名	类型	备注
dataset_name	LowCardinality(String)	Name of the dataset this example belongs to
function_name	LowCardinality(String)	Name of the function this example is for
id	UUID	Must be a UUIDv7, often the inference ID if generated from an inference
episode_id	UUID	Must be a UUIDv7
input	String (JSON)	input field in the /inference request body
output	String (JSON)	Object with parsed and raw fields
output_schema	String (JSON)	Schema that the output must conform to
tags	Map(String, String)	User-assigned tags (e.g. {"user_id": "123"})
auxiliary	String	Additional JSON data (unstructured)
is_deleted	Bool	Soft deletion flag, defaults to false
updated_at	DateTime	When this dataset entry was updated, defaults to now()

该表使用ReplacingMergeTree引擎，包含updated_at和is_deleted列用于去重。 表数据按dataset_name、function_name和id排序，以优化按数据集和函数筛选的查询性能。

BatchRequest

BatchRequest 表存储了向模型提供商发起的批量请求信息。每当创建或轮询特定的 batch_id 时，我们都会更新该表。

列名	类型	备注
batch_id	UUID	Must be a UUIDv7
id	UUID	Must be a UUIDv7
batch_params	String	Parameters used for the batch request
model_name	String	Name of the model used
model_provider_name	String	Name of the model provider
status	String	One of: ‘pending’, ‘completed’, ‘failed’
errors	Array(String)	Array of error messages if status is ‘failed’
timestamp	DateTime	Materialized from id (using UUIDv7ToDateTime function)
raw_request	String	Raw request sent to the model provider
raw_response	String	Raw response received from the model provider
function_name	String	Name of the function being called
variant_name	String	Name of the function variant

BatchModelInference

BatchModelInference表存储了作为批量请求一部分进行的推理信息。一旦请求成功，我们将使用这些信息来填充ChatInference、JsonInference和ModelInference表。

列名	类型	备注
inference_id	UUID	Must be a UUIDv7
batch_id	UUID	Must be a UUIDv7
function_name	String	Name of the function being called
variant_name	String	Name of the function variant
episode_id	UUID	Must be a UUIDv7
input	String (JSON)	input field in the /inference request body
system	String	The system input to the model
input_messages	Array(RequestMessage)	The user and assistant messages input to the model
tool_params	String (JSON)	Object with any tool parameters (e.g. tool_choice, available_tools) used for the inference
inference_params	String (JSON)	Object with any inference parameters per variant type (e.g. {"chat_completion": {"temperature": 0.5}})
raw_request	String	Raw request sent to the model provider
model_name	String	Name of the model used
model_provider_name	String	Name of the model provider
output_schema	String	Optional schema for JSON outputs
tags	Map(String, String)	User-assigned tags (e.g. {"author": "Alice"})
timestamp	DateTime	Materialized from id (using UUIDv7ToDateTime function)

Materialized View Tables

Materialized views 在ClickHouse等列式数据库中预先计算数据的替代索引，与实时计算结果相比，显著提高了查询性能。 在TensorZero的场景中，我们在以下物化视图中存储了关于推理和反馈的非规范化数据，以支持常见下游用例的高效查询。

FeedbackTag

FeedbackTag表存储与各类反馈类型关联的标签。这些标签用于对反馈条目进行分类并添加元数据，以便后续进行用户自定义筛选。数据通过物化视图从BooleanMetricFeedback、CommentFeedback、DemonstrationFeedback和FloatMetricFeedback表中读取后插入到此表。

列名	类型	备注
metric_name	String	Name of the metric the tag is associated with.
key	String	Key of the tag.
value	String	Value of the tag.
feedback_id	UUID	UUID referencing the related feedback entry (e.g., BooleanMetricFeedback.id).

InferenceById

InferenceById表是一个物化视图，它结合了来自ChatInference和JSONInference的数据。 值得注意的是，它通过id_uint对表进行索引，以便网关快速查找以验证反馈请求。 我们将id_uint存储为UInt128类型，这样它们就能按时间自然排序，因为ClickHouse以小端序对UUID进行排序。

列名	类型	备注
id_uint	UInt128	Integer representation of UUIDv7 for sorting order
function_name	String
variant_name	String
episode_id	UUID	Must be a UUIDv7
function_type	String	Either 'chat' or 'json'

InferenceByEpisodeId

InferenceByEpisodeId表是一个物化视图，通过剧集ID对推理结果建立索引，从而支持高效查询某个剧集中的所有推理记录。 我们将episode_id_uint存储为UInt128类型，这样它们就能按时间自然排序，因为ClickHouse采用小端序对UUID进行排序。

列名	类型	备注
episode_id_uint	UInt128	Integer representation of UUIDv7 for sorting order
id_uint	UInt128	Integer representation of UUIDv7 for sorting order
function_name	String	Name of the function being called
variant_name	String	Name of the function variant
function_type	Enum(‘chat’, ‘json’)	Type of function (chat or json)

InferenceTag

InferenceTag表存储与推理相关的标签。标签用于对推理进行分类并添加元数据，以便后续进行用户自定义筛选。数据通过物化视图从ChatInference和JsonInference表中读取后插入到此表。

列名	类型	备注
function_name	String	Name of the function the tag is associated with.
key	String	Key of the tag.
value	String	Value of the tag.
inference_id	UUID	UUID referencing the related inference (e.g., ChatInference.id).

BatchIdByInferenceId

BatchIdByInferenceId 表将推理ID映射至批次ID，可高效查询某个推理所属的批次。

列名	类型	备注
inference_id	UUID	Must be a UUIDv7
batch_id	UUID	Must be a UUIDv7

BooleanMetricFeedbackByTargetId

BooleanMetricFeedbackByTargetId 表通过目标ID索引布尔指标反馈，实现对特定目标反馈的高效查询。

列名	类型	备注
id	UUID	Must be a UUIDv7
target_id	UUID	Must be a UUIDv7
metric_name	String	Name of the metric (stored as LowCardinality)
value	Bool	The boolean feedback value
tags	Map(String, String)	Key-value pairs of tags associated with the feedback

CommentFeedbackByTargetId

CommentFeedbackByTargetId 表存储与推理或事件相关的文本反馈，支持通过目标ID高效查询评论。

列名	类型	备注
id	UUID	Must be a UUIDv7
target_id	UUID	Must be a UUIDv7
target_type	Enum(‘inference’, ‘episode’)	Type of entity this feedback is for
value	String	The text feedback content
tags	Map(String, String)	Key-value pairs of tags associated with the feedback

DemonstrationFeedbackByInferenceId

DemonstrationFeedbackByInferenceId 表存储与推理相关的演示反馈数据，支持通过推理ID快速查询演示记录。

列名	类型	备注
id	UUID	Must be a UUIDv7
inference_id	UUID	Must be a UUIDv7
value	String	The demonstration feedback content
tags	Map(String, String)	Key-value pairs of tags associated with the feedback

FloatMetricFeedbackByTargetId

FloatMetricFeedbackByTargetId 表通过目标ID对浮点指标反馈进行索引，从而实现对特定目标反馈的高效查询。

列名	类型	备注
id	UUID	Must be a UUIDv7
target_id	UUID	Must be a UUIDv7
metric_name	String	Name of the metric (stored as LowCardinality)
value	Float32	The float feedback value
tags	Map(String, String)	Key-value pairs of tags associated with the feedback