4. 配置文件编写入门

DeepStream 应用的开发与部署，其核心工作之一便是编写符合业务需求的配置文件。配置文件（通常以 .txt 或 .cfg 结尾）是 DeepStream 管道（Pipeline）的“施工图纸”，它通过键值对（Key-Value）的形式，声明了数据从何处来（source）、经过何种算法处理（primary gie）、最终流向何处（sink）。对于项目交付而言，一份结构清晰、参数合理的配置文件，其价值不亚于模型本身。本章将聚焦于如何从零开始编写一个基础的 DeepStream 配置文件，深入剖析 source、sink、primary gie 三大核心组件的配置语法、常用参数及背后的工程逻辑。

上图展示了 DeepStream 配置文件中三个核心组件的基本构成与数据流向。在实际工程中，配置文件不仅包含这三个部分，还可能涉及 streammux（多路流复用）、tracker（跟踪器）、osd（屏幕显示）等。但无论管道多么复杂，source、primary-gie、sink 始终是构成最小可用系统的“铁三角”。理解这三者的配置，是后续学习高级组件和性能调优的基石。

4.1 核心原理：配置文件如何驱动 GStreamer 管道

DeepStream 的配置文件本质上是 GStreamer 管道元素的属性描述集合。当 DeepStream 应用（如 deepstream-app）启动时，解析器会读取该文件，并根据其中的组（Group）和键值对，动态创建 GStreamer 元素并连接它们。这种设计将“管道逻辑”与“业务参数”分离，使得算法工程师无需修改 C++/Python 代码，仅通过编辑文本文件即可调整输入源、模型路径、输出格式等关键属性。

配置文件的语法遵循 INI 文件风格：[组名] 定义了一个组件实例，其下的 键=值 定义了该组件的属性。例如，[source0] 下的 type=filesource 告诉 DeepStream 创建一个文件读取源。理解这一机制的关键在于：每个组名对应一个特定的插件类型，而组内的键值对则直接映射到该插件的 GObject 属性。因此，编写配置文件的前提是熟悉 GStreamer 插件属性命名规则。

4.2 操作流程：从零编写一个最小化配置文件

编写配置文件的流程可以归纳为“四步法”：确定输入源 → 配置推理引擎 → 配置输出 → 设置全局属性。以下以一个读取本地视频文件、使用 TensorRT 模型进行检测、并将结果编码为 H.264 视频文件的场景为例，演示完整流程。

步骤 1：配置 source（输入源）

输入源决定了数据从哪来。DeepStream 支持多种输入类型，包括文件（filesource）、实时流（camera 或 rtsp）、以及多路流（通过 num-sources 控制）。对于文件输入，核心参数是 uri，它必须使用标准的文件 URL 格式。

[source0]
# 输入源类型：文件、摄像头、RTSP
type=filesource
# 文件路径，必须使用 file:// 前缀
uri=file:///opt/nvidia/deepstream/deepstream/samples/streams/sample_720p.h264
# 输入源数量，多路流时设置为 >1
num-sources=1
# 是否循环播放，0 为不循环，-1 为无限循环
loop=0

对于 RTSP 摄像头输入，只需将 type 改为 rtsp，并将 uri 设置为 rtsp://username:password@ip:port/stream1。需要注意的是，num-sources 与 uri 的配合：当 num-sources > 1 时，DeepStream 会自动将多个相同类型的输入源进行批处理（batch），这对于提升 GPU 利用率至关重要。

步骤 2：配置 primary-gie（主推理引擎）

primary-gie 是管道中执行目标检测/分类的组件。它本身不包含模型，而是通过 config-file-path 指向一个独立的模型配置文件（通常为 config_infer_*.txt），该文件定义了模型路径、输入输出张量名、预处理参数等。在管道配置文件中，我们主要关注 GIE 的使能状态、批处理大小和与前后组件的交互。

[primary-gie]
# 是否启用主推理引擎
enable=1
# 指向模型推理配置文件（包含模型路径、精度、预处理等）
config-file-path=config_infer_primary.txt
# 批处理大小，必须与 source 的 num-sources 匹配或为其整数倍
batch-size=1
# 推理精度：1=FP32, 2=FP16, 3=INT8
interval=0
# 与 streammux 的批处理超时时间（微秒），用于凑齐 batch-size
gie-unique-id=1

这里特别强调 batch-size 与 num-sources 的关系。如果 num-sources=4，而 batch-size=1，则 GPU 推理单元每次只处理 1 帧，导致 4 路输入无法共享一次推理计算，造成算力浪费。通常建议 batch-size 等于 num-sources，或者设置为 2 的幂次方（如 1、2、4、8）以适配 TensorRT 的优化。

步骤 3：配置 sink（输出）

sink 决定了处理结果的去向。常见的 sink 类型包括：filesink（输出到文件）、fakesink（丢弃数据，用于性能测试）、eglrender（屏幕显示）、rtsp（推流）。对于项目交付，文件输出和 RTSP 推流是最常见的两种。

[sink0]
# 输出类型：filesink / fakesink / eglrender / rtsp
type=filesink
# 编码格式：H264 / H265 / MPEG4
codec=H264
# 编码比特率（kbps）
bitrate=4000000
# 输出文件路径
file=output.mp4
# 是否同步输出，1 表示按帧率输出，0 表示尽可能快
sync=0

当需要同时进行屏幕预览和文件保存时，可以配置多个 sink。例如，[sink1] 设置为 type=eglrender 用于实时显示，[sink0] 保持文件输出。DeepStream 会自动在管道末端创建 tee 组件进行数据分发。

步骤 4：设置全局属性（可选但重要）

在文件开头，通常有一个 [application] 或 [tiled-display] 组，用于配置全局行为。例如，enable-perf-measurement 控制是否打印 FPS 性能日志，gpu-id 指定使用哪块 GPU。

[application]
# 是否启用性能测量
enable-perf-measurement=1
# 性能测量间隔（秒）
perf-measurement-interval=1
# 使用的 GPU 设备 ID
gpu-id=0

4.3 案例拆解：一个完整的车辆检测与输出配置

为了将上述步骤串联起来，我们构建一个实际案例：对一段包含车辆的监控视频进行检测，并将结果保存为带标注框的 H.264 视频。该案例将展示配置文件各组件如何协同工作，并暴露常见的配置陷阱。

场景与约束：输入视频为 1080p、30fps 的本地文件；使用 DeepStream 自带的 resnet10.caffemodel 模型（用于车辆/行人检测）；要求输出视频包含检测框，且帧率不低于 25fps。硬件平台为 Jetson AGX Xavier。

初始配置与问题：工程师首先编写了如下配置：

[source0]
type=filesource
uri=file:///opt/nvidia/deepstream/deepstream/samples/streams/sample_720p.h264
num-sources=1

[primary-gie]
enable=1
config-file-path=config_infer_primary.txt
batch-size=1

[sink0]
type=filesink
codec=H264
file=output.mp4

运行后，虽然能生成输出文件，但 FPS 仅为 18，且 GPU 利用率只有 40%。通过 nvidia-smi 观察，发现 GPU 编码器（NVDEC/NVENC）利用率不高，而 GPU 计算单元（CUDA）存在空闲。

分析与调整：问题出在 batch-size=1 和缺少 streammux 的批处理超时配置。对于单路输入，虽然 batch-size=1 是合理的，但 DeepStream 默认的 streammux 批处理超时（batched-push-timeout）为 40000 微秒（40ms），这导致即使只有一路输入，管道也会等待 40ms 凑批，从而限制了帧率。解决方法是显式添加 [streammux] 组并降低超时时间。

[streammux]
# 批处理超时时间（微秒），降低以减少延迟
batched-push-timeout=10000
# 批处理宽度和高度，用于统一输入尺寸
width=1280
height=720
# 批处理帧率
batch-size=1

修改后，FPS 提升至 28，GPU 利用率达到 70%。此外，为了确保输出视频包含检测框，还需要在 [sink0] 之前启用 OSD（屏幕显示）组件。在配置文件中，这通常通过添加 [osd] 组实现：

[osd]
# 启用 OSD
enable=1
# 显示检测框、标签和置信度
display-text=1
display-bbox=1
# 字体大小
font-size=14

结果与复盘：最终配置在 Jetson AGX Xavier 上实现了 28fps 的实时处理，输出视频清晰包含检测框。复盘经验如下：

• 不要忽略 streammux 的批处理超时参数，它是影响单路输入延迟的关键。
• OSD 组件是“显示”而非“编码”的一部分，若需在输出视频中看到框，必须显式启用。
• 性能调优应从“最小配置”开始，先保证功能正确，再逐步增加组件并观察 FPS 变化。

4.4 常见误区与总结复盘

在编写配置文件的过程中，新手和资深工程师都会遇到一些典型问题。以下通过表格形式总结常见误区、现象及解决方案。

常见误区	典型现象	解决方案
忽略 streammux 的批处理超时	单路输入 FPS 远低于预期，GPU 利用率低	显式添加 [streammux] 组，设置 batched-push-timeout=10000 或更低
batch-size 与 num-sources 不匹配	多路输入时推理延迟高，或报错“batch size mismatch”	确保 batch-size 是 num-sources 的整数倍，且不超过模型支持的最大 batch
忘记启用 OSD 导致输出视频无框	输出视频正常但无检测框	添加 [osd] 组并设置 enable=1，同时确认 display-bbox=1
路径使用路径且包含空格	应用启动时报错“file not found”	使用 file:// 前缀，并对空格进行 %20 编码，或使用相对路径
混淆 interval 与 batch-size	推理结果跳帧或重复	interval 表示跳帧推理（0 表示每帧都推理），batch-size 表示一次推理的帧数

总结复盘：编写 DeepStream 配置文件的核心在于理解“组件-属性-数据流”三者的关系。一个健壮的配置文件应具备以下特征：明确的输入输出声明、合理的批处理策略、显式的资源控制（如 GPU ID）、以及可移植的路径管理。在项目交付阶段，建议将配置文件与模型文件、标签文件、推理配置文件一并打包，并编写一个简单的启动脚本，确保环境一致性。此外，利用 deepstream-app --version 和 gst-inspect-1.0 工具验证插件属性，可以避免因拼写错误导致的运行时崩溃。