车辆信号目录

指标配置生成器 (MCG) 通过检查信号名称、对表达式执行类型检查以及推断输出类型来验证指标配置。MCG 需要访问车辆信号的协议缓冲区 (protobuf) 消息定义，才能执行这些任务。

在 SDV 中，车辆信号和服务使用车辆服务接口定义语言 (VSIDL) 进行定义。VSIDL 使用 protobuf 文件来指定消息，这些 protobuf 文件构成了信号目录的基础。

如需使信号定义可供 MCG 使用，您必须将这些 VSIDL protobuf 文件打包到 protobuf FileDescriptorSet 中，并将其上传到 MCG 服务。MCG 使用术语车辆信号目录来指代这些已上传且已版本化的定义集（本质上，车辆信号目录是 VSIDL 目录中 proto 消息定义的已编译、已上传形式）。

什么是车辆信号目录？

车辆信号目录为 MCG 提供用于验证的信号定义，这些定义打包为 protobuf FileDescriptorSet。

在 MCG 中，目录由您在上传期间分配的版本字符串标识，这样您就可以管理多个不同的信号定义集。例如，您可能会为软件版本（v1.0、v1.1、v2.0）或不同的车型或硬件配置（suv-my2025、sedan-my2025）维护不同的目录版本。每个指标配置都使用 vs_version 字段来引用特定目录，该目录定义了可用作数据源的信号，并为类型推理和验证提供了信号定义。

创建 FileDescriptorSet 的实例

如定义消息和 RPC 服务中所述，车辆信号在 protobuf 文件中定义为 protobuf 消息。如果您参与了 SDV 项目，请使用项目 VSIDL 目录中的 protobuf 文件创建 FileDescriptorSet 的实例。

如需为 MCG 创建目录，请使用 protoc 将 protobuf 文件打包到 FileDescriptorSet 二进制文件中。如果您的所有 protobuf 文件都在一个文件夹中，请运行以下命令来生成 vehicle_signals.pb：

protoc --include_imports --descriptor_set_out=vehicle_signals.pb path/to/your/protos/*.proto

上传和管理目录

将信号定义集作为目录上传后，您可以在指标配置请求中按版本名称引用该信号定义集。

添加或更新目录版本

生成 vehicle_signals.pb 目录文件后，您可以使用 /api/v2/vs/ 下的 MCG API 端点上传和管理该文件。用于添加或更新目录的端点 POST /api/v2/vs/ 要求在 JSON 载荷中将 FileDescriptorSet 作为 base64 编码的字符串传递。

如需对 vehicle_signals.pb 进行编码以供 API 使用，请使用 base64 命令。-w 0 标志会停用换行，以便编码后的字符串显示在单行中：

VEHICLE_SIGNALS_BASE64=$(base64 -w 0 vehicle_signals.pb)

如需将 vehicle_signals.pb 作为新版本（例如 v1.0）上传或更新现有版本，请向 /api/v2/vs/ 端点发送包含 base64 编码内容的 POST 请求，并提供唯一的版本名称。

请求正文必须是包含 version 字符串和 base64 编码的 vehicle_signals 字符串的 JSON 对象：

{
  "version": "v1.0",
  "vehicle_signals": "Q2lSb1pYB3jCRkRt..."
}

以下示例展示了如何使用 curl 将 vehicle_signals.pb 上传为版本 v1.0。该示例使用 printf 构造 JSON 载荷，并将其通过管道传输到 curl，这样就无需创建包含超长单行 base64 字符串的 JSON 文件：

# 1. Encode the FileDescriptorSet to a Base64 string
VEHICLE_SIGNALS_BASE64=$(base64 -w 0 vehicle_signals.pb)

# 2. Define catalog version and build JSON payload
VERSION="v1.0"
JSON_PAYLOAD=$(jq -n --arg v "$VERSION" --arg d "$VEHICLE_SIGNALS_BASE64" \
  '{version: $v, vehicle_signals: $d}')

# 3. POST the data to the API endpoint
echo "$JSON_PAYLOAD" | curl -H "Content-Type: application/json" --data-binary @- "$SERVICE_URL/api/v2/vs/"

列出和删除版本

您可以列出所有可用的目录版本，也可以删除特定版本：

  • 列出版本：如需查看所有已上传目录版本的标识符列表，请向 /api/v2/vs/ 发送 GET 请求。请参阅 GET /api/v2/vs/。

  • 删除版本：如需移除目录，请向 /api/v2/vs/{version} 发送 DELETE 请求，其中 {version} 是上传目录时提供的标识符（例如 v1.0）。请参阅 DELETE /api/v2/vs/{version}。

如需详细了解所有端点，请参阅 API 参考文档。

在指标配置中使用目录

上传后，使用 vs_version 字段在指标配置中引用目录版本：

{ "vs_version": "v1.0", ... }

当此 JSON 对象发送到 /api/v2/generate_metrics_config 或 /api/v2/validate_metrics_config 端点时，MCG 会使用 v1.0 目录中的信号定义来执行验证和类型推断。