指标配置生成器 (MCG) 通过检查信号名称、对表达式执行类型检查和推断输出类型来验证指标配置。MCG 需要访问车辆信号的协议缓冲区 (protobuf) 消息定义才能执行这些任务。
在 SDV 中，车辆信号和服务使用车辆服务接口定义语言 (VSIDL) 进行定义。VSIDL 使用 protobuf 文件来指定消息，而这些 protobuf 文件构成了信号目录的基础。
如需让 MCG 可以使用信号定义，您必须将这些 VSIDL protobuf 文件打包到 protobuf FileDescriptorSet 中，并将其上传到 MCG 服务。MCG 使用术语车辆信号目录来指代这些已上传且已纳入版本控制的定义集（从本质上讲，车辆信号目录是 VSIDL 目录中 proto 消息定义的已编译、已上传形式）。
什么是车辆信号目录？
车辆信号目录以 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 <var label="path to folder with .proto files">path/to/your/protos</var>/*.proto
上传和管理目录
将信号定义集作为目录上传后，您可以在指标配置请求中按版本名称引用该信号定义集。
添加或更新目录版本
生成 vehicle_signals.pb 目录文件后，您可以使用 /api/v1/vs/ 下的 MCG API 端点上传和管理该文件。用于添加或更新目录的端点 POST /api/v1/vs/ 要求在 JSON 载荷中以 base64 编码的字符串形式传递 FileDescriptorSet。
如需对 vehicle_signals.pb 进行编码以供 API 使用，请使用 base64 命令。-w 0 标志会停用自动换行功能，以便编码后的字符串显示在单行中：
VEHICLE_SIGNALS_BASE64=$(base64 -w 0 vehicle_signals.pb)
如需将 vehicle_signals.pb 上传为新版本（例如 v1.0）或更新现有版本，请向 /api/v1/vs/ 端点发送 POST 请求，其中包含以 base64 编码的内容以及唯一的版本名称。
请求正文必须是一个 JSON 对象，其中包含 version 字符串和 base64 编码的 vehicle_signals 字符串：
{
"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="<var label="catalog version">v1.0</var>"
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/v1/vs/"
列出和删除版本
您可以列出所有可用的目录版本，也可以删除特定版本：
列出版本：如需查看所有已上传目录版本的标识符列表，请向
/api/v1/vs/发送GET请求。请参阅 GET /api/v1/vs/。删除版本：如需移除目录，请向
/api/v1/vs/{version}发送DELETE请求，其中{version}是上传目录时提供的标识符（例如v1.0）。请参阅 DELETE /api/v1/vs/{version}。
如需详细了解所有端点，请参阅 API 参考文档。
在指标配置中使用目录
上传后，在指标配置中使用 vs_version 字段引用目录版本：
{ "vs_version": "v1.0", ... }
当此 JSON 对象发送到 /api/v1/generate_metrics_config 或 /api/v1/validate_metrics_config 端点时，MCG 会使用 v1.0 目录中的信号定义来执行验证和类型推断。