561 lines
17 KiB
Markdown
561 lines
17 KiB
Markdown
# DeepCam - VisionProcessor C++ Library
|
||
|
||
这个项目将Qwen多模态大模型的视觉预处理Python代码转换为高性能的C++实现。VisionProcessor库提供了完整的图像和视频预处理功能，以及Qwen2VL处理器，专为多模态AI应用设计。
|
||
|
||
## 🎯 特性
|
||
|
||
- **🖼️ 图像处理**: 支持多种图像格式（JPG, PNG, BMP, TIFF, WebP等）
|
||
- **🎬 视频处理**: 支持主流视频格式（MP4, AVI, MOV, MKV等）
|
||
- **🧠 智能调整大小**: 基于像素约束和纵横比的智能调整算法
|
||
- **🌐 多种输入源**: 支持本地文件、HTTP/HTTPS URL和Base64编码
|
||
- **⚡ 高性能**: 使用OpenCV优化的图像处理算法
|
||
- **🎛️ 灵活配置**: 丰富的参数配置选项
|
||
- **🔒 内存安全**: RAII和现代C++内存管理
|
||
- **📹 智能帧采样**: 高效的视频帧采样算法
|
||
- **🤖 Qwen2VL处理器**: 完整的多模态处理器，支持图像、视频和文本的联合处理
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
project-root/ # 项目根目录
|
||
├── CMakeLists.txt # 主CMake配置文件
|
||
├── README.md # 项目说明文档
|
||
├── deepcam/ # DeepCam源代码目录
|
||
│ └── sources/ # 源代码子目录
|
||
│ ├── CMakeLists.txt # 库CMake配置
|
||
│ ├── vision_process.hpp # 视觉处理头文件
|
||
│ ├── vision_process.cc # 视觉处理实现文件
|
||
│ ├── qwen2_vl_processor.hpp # Qwen2VL处理器头文件
|
||
│ └── qwen2_vl_processor.cc # Qwen2VL处理器实现文件
|
||
└── test/ # 测试和示例目录
|
||
├── CMakeLists.txt # 测试CMake配置
|
||
├── vision_process_example.cpp # 视觉处理使用示例
|
||
└── qwen2_vl_example.cpp # Qwen2VL处理器使用示例
|
||
```
|
||
|
||
## 🛠️ 依赖
|
||
|
||
### 必需依赖
|
||
- **OpenCV 4.x**: 图像和视频处理 (`libopencv-dev`)
|
||
- **libcurl**: HTTP请求支持 (`libcurl4-openssl-dev`)
|
||
- **CMake 3.10+**: 构建系统
|
||
- **C++17**: 现代C++标准支持
|
||
|
||
### 可选依赖
|
||
- **jsoncpp**: JSON配置文件解析 (`libjsoncpp-dev`) - AutoProcessor功能需要
|
||
|
||
### 系统要求
|
||
- **Linux**: Ubuntu 18.04+ / CentOS 7+ / 其他主流发行版
|
||
- **macOS**: 10.14+ (支持Homebrew)
|
||
- **编译器**: GCC 7+ / Clang 6+ / MSVC 2017+
|
||
|
||
## 📦 安装依赖
|
||
|
||
### Ubuntu/Debian
|
||
```bash
|
||
sudo apt-get update
|
||
sudo apt-get install libopencv-dev libcurl4-openssl-dev cmake build-essential pkg-config
|
||
|
||
# 可选：安装jsoncpp以支持AutoProcessor
|
||
sudo apt-get install libjsoncpp-dev
|
||
```
|
||
|
||
### macOS (使用Homebrew)
|
||
```bash
|
||
brew install opencv curl cmake pkg-config
|
||
|
||
# 可选：安装jsoncpp以支持AutoProcessor
|
||
brew install jsoncpp
|
||
```
|
||
|
||
### CentOS/RHEL
|
||
```bash
|
||
sudo yum install opencv-devel libcurl-devel cmake3 gcc-c++ pkgconfig
|
||
|
||
# 可选：安装jsoncpp以支持AutoProcessor (EPEL仓库)
|
||
sudo yum install epel-release
|
||
sudo yum install jsoncpp-devel
|
||
|
||
# 或者在较新版本上使用 dnf
|
||
sudo dnf install opencv-devel libcurl-devel cmake gcc-c++ pkgconf-pkg-config jsoncpp-devel
|
||
```
|
||
|
||
## 🔨 编译
|
||
|
||
```bash
|
||
# 进入项目根目录
|
||
cd project-root
|
||
|
||
# 创建构建目录
|
||
mkdir build && cd build
|
||
|
||
# 配置CMake
|
||
cmake ..
|
||
|
||
# 编译
|
||
make -j$(nproc)
|
||
|
||
# 可选：安装到系统
|
||
sudo make install
|
||
```
|
||
|
||
### 编译选项
|
||
```bash
|
||
# Debug模式编译
|
||
cmake -DCMAKE_BUILD_TYPE=Debug ..
|
||
|
||
# Release模式编译（默认）
|
||
cmake -DCMAKE_BUILD_TYPE=Release ..
|
||
|
||
# 指定OpenCV路径（如果需要）
|
||
cmake -DOpenCV_DIR=/path/to/opencv ..
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 基本用法
|
||
|
||
```cpp
|
||
#include "vision_process.hpp"
|
||
|
||
int main() {
|
||
// 创建处理器实例
|
||
VisionProcessor processor;
|
||
|
||
// 处理单张图像
|
||
std::map<std::string, std::string> imageConfig;
|
||
imageConfig["image"] = "/path/to/image.jpg";
|
||
imageConfig["min_pixels"] = "3136";
|
||
imageConfig["max_pixels"] = "12845056";
|
||
|
||
try {
|
||
cv::Mat processedImage = processor.fetchImage(imageConfig);
|
||
std::cout << "图像处理成功！尺寸: "
|
||
<< processedImage.cols << "x" << processedImage.rows << std::endl;
|
||
} catch (const std::exception& e) {
|
||
std::cerr << "错误: " << e.what() << std::endl;
|
||
}
|
||
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
### 处理视频
|
||
|
||
```cpp
|
||
// 配置视频处理参数
|
||
std::map<std::string, std::string> videoConfig;
|
||
videoConfig["video"] = "/path/to/video.mp4";
|
||
videoConfig["fps"] = "2.0"; // 采样帧率
|
||
videoConfig["min_frames"] = "4"; // 最少帧数
|
||
videoConfig["max_frames"] = "32"; // 最多帧数
|
||
videoConfig["video_start"] = "10.0"; // 开始时间（秒）
|
||
videoConfig["video_end"] = "60.0"; // 结束时间（秒）
|
||
|
||
std::vector<cv::Mat> frames = processor.fetchVideo(videoConfig);
|
||
std::cout << "提取了 " << frames.size() << " 帧" << std::endl;
|
||
```
|
||
|
||
### Qwen2VL处理器用法
|
||
|
||
```cpp
|
||
#include "qwen2_vl_processor.hpp"
|
||
|
||
int main() {
|
||
// 创建模拟的处理器组件
|
||
auto image_processor = std::make_shared<MockImageProcessor>();
|
||
auto video_processor = std::make_shared<MockVideoProcessor>();
|
||
auto tokenizer = std::make_shared<MockTokenizer>();
|
||
|
||
// 创建Qwen2VL处理器
|
||
Qwen2VLProcessor processor(image_processor, tokenizer, video_processor);
|
||
|
||
// 处理包含图像的文本
|
||
TextInput text = "描述这张图片: <|image_pad|> 你看到了什么？";
|
||
cv::Mat image = cv::imread("/path/to/image.jpg");
|
||
ImageInput image_input = image;
|
||
|
||
// 配置处理参数
|
||
ProcessorKwargs kwargs;
|
||
kwargs.text_kwargs["return_tensors"] = "pt";
|
||
kwargs.text_kwargs["return_mm_token_type_ids"] = "true";
|
||
|
||
try {
|
||
// 进行多模态处理
|
||
BatchFeature result = processor(image_input, text, std::nullopt, kwargs);
|
||
|
||
std::cout << "处理成功！" << std::endl;
|
||
std::cout << "结果包含的数据键: ";
|
||
for (const auto& [key, value] : result.data) {
|
||
std::cout << key << " ";
|
||
}
|
||
std::cout << std::endl;
|
||
|
||
} catch (const std::exception& e) {
|
||
std::cerr << "错误: " << e.what() << std::endl;
|
||
}
|
||
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
### 计算多模态token数量
|
||
|
||
```cpp
|
||
// 计算图像和视频所需的token数量
|
||
std::vector<std::pair<int, int>> image_sizes = {{224, 224}, {448, 448}};
|
||
std::vector<std::tuple<int, int, int>> video_sizes = {{8, 224, 224}};
|
||
|
||
MultiModalData mm_data = processor.getNumMultimodalTokens(image_sizes, video_sizes);
|
||
|
||
if (mm_data.num_image_tokens.has_value()) {
|
||
std::cout << "图像token数量: ";
|
||
for (int count : mm_data.num_image_tokens.value()) {
|
||
std::cout << count << " ";
|
||
}
|
||
std::cout << std::endl;
|
||
}
|
||
```
|
||
|
||
### 批量处理
|
||
|
||
```cpp
|
||
// 处理包含多媒体的会话数据
|
||
std::vector<std::map<std::string, std::string>> conversations;
|
||
|
||
// 添加图像
|
||
std::map<std::string, std::string> imageItem;
|
||
imageItem["type"] = "image";
|
||
imageItem["image"] = "/path/to/image.jpg";
|
||
conversations.push_back(imageItem);
|
||
|
||
// 添加视频
|
||
std::map<std::string, std::string> videoItem;
|
||
videoItem["type"] = "video";
|
||
videoItem["video"] = "/path/to/video.mp4";
|
||
videoItem["fps"] = "2.0";
|
||
conversations.push_back(videoItem);
|
||
|
||
// 处理所有媒体
|
||
ProcessResult result = processor.processVisionInfo(conversations, true);
|
||
|
||
std::cout << "处理结果:" << std::endl;
|
||
std::cout << "- 图像数量: " << result.imageInputs.size() << std::endl;
|
||
std::cout << "- 视频数量: " << result.videoInputs.size() << std::endl;
|
||
```
|
||
|
||
### AutoProcessor用法（工厂模式）
|
||
|
||
```cpp
|
||
#include "auto_processor.hpp"
|
||
|
||
int main() {
|
||
try {
|
||
// 方法1: 从预训练模型目录加载
|
||
FromPretrainedKwargs kwargs;
|
||
kwargs.trust_remote_code = true;
|
||
|
||
auto processor = AutoProcessor::fromPretrained("/path/to/model", kwargs);
|
||
|
||
// 方法2: 注册自定义处理器
|
||
AutoProcessor::registerProcessor("custom_model", [](const std::string& path, const FromPretrainedKwargs& kwargs) {
|
||
// 创建自定义处理器的逻辑
|
||
return createCustomProcessor(path, kwargs);
|
||
});
|
||
|
||
// 使用处理器
|
||
TextInput text = "描述这个图像: <|image_pad|>";
|
||
cv::Mat image = cv::imread("image.jpg");
|
||
|
||
ProcessorKwargs proc_kwargs;
|
||
auto result = processor(ImageInput(image), text, std::nullopt, proc_kwargs);
|
||
|
||
std::cout << "处理完成！" << std::endl;
|
||
|
||
} catch (const std::exception& e) {
|
||
std::cerr << "错误: " << e.what() << std::endl;
|
||
}
|
||
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
## 📖 API 参考
|
||
|
||
### VisionProcessor 类
|
||
|
||
#### 主要方法
|
||
|
||
| 方法 | 说明 | 返回值 |
|
||
|------|------|--------|
|
||
| `fetchImage()` | 处理单张图像 | `cv::Mat` |
|
||
| `fetchVideo()` | 处理视频文件 | `std::vector<cv::Mat>` |
|
||
| `processVisionInfo()` | 批量处理会话数据 | `ProcessResult` |
|
||
|
||
#### 工具函数
|
||
|
||
| 函数 | 说明 | 参数 |
|
||
|------|------|------|
|
||
| `smartResize()` | 智能调整尺寸 | `height, width, factor, minPixels, maxPixels` |
|
||
| `roundByFactor()` | 按因子四舍五入 | `number, factor` |
|
||
| `ceilByFactor()` | 按因子向上取整 | `number, factor` |
|
||
| `floorByFactor()` | 按因子向下取整 | `number, factor` |
|
||
|
||
### 配置参数
|
||
|
||
#### 图像配置
|
||
```cpp
|
||
std::map<std::string, std::string> config;
|
||
config["image"] = "path/to/image.jpg"; // 图像路径
|
||
config["image_url"] = "http://example.com/image.jpg"; // 或使用URL
|
||
config["min_pixels"] = "3136"; // 最小像素数 (默认: 4*28*28)
|
||
config["max_pixels"] = "12845056"; // 最大像素数 (默认: 16384*28*28)
|
||
config["resized_height"] = "224"; // 指定高度
|
||
config["resized_width"] = "224"; // 指定宽度
|
||
```
|
||
|
||
#### 视频配置
|
||
```cpp
|
||
std::map<std::string, std::string> config;
|
||
config["video"] = "path/to/video.mp4"; // 视频路径
|
||
config["fps"] = "2.0"; // 采样帧率 (默认: 2.0)
|
||
config["nframes"] = "16"; // 或直接指定帧数
|
||
config["min_frames"] = "4"; // 最小帧数 (默认: 4)
|
||
config["max_frames"] = "768"; // 最大帧数 (默认: 768)
|
||
config["video_start"] = "10.0"; // 开始时间（秒）
|
||
config["video_end"] = "60.0"; // 结束时间（秒）
|
||
config["min_pixels"] = "100352"; // 最小像素数 (默认: 128*28*28)
|
||
config["max_pixels"] = "602112"; // 最大像素数 (默认: 768*28*28)
|
||
```
|
||
|
||
## 🎨 支持的输入格式
|
||
|
||
### 图像格式
|
||
- **本地文件**: `"/path/to/image.jpg"`
|
||
- **HTTP URL**: `"http://example.com/image.jpg"`
|
||
- **HTTPS URL**: `"https://example.com/image.jpg"`
|
||
- **Base64编码**: `"data:image/jpeg;base64,/9j/4AAQ..."`
|
||
- **File URI**: `"file:///path/to/image.jpg"`
|
||
|
||
### 视频格式
|
||
- **本地文件**: `"/path/to/video.mp4"`
|
||
- **File URI**: `"file:///path/to/video.mp4"`
|
||
|
||
### 支持的文件扩展名
|
||
- **图像**: `.jpg`, `.jpeg`, `.png`, `.bmp`, `.tiff`, `.tif`, `.webp`
|
||
- **视频**: `.mp4`, `.avi`, `.mov`, `.mkv`, `.wmv`, `.flv`, `.webm`
|
||
|
||
## ⚙️ 高级配置
|
||
|
||
### 环境变量
|
||
```bash
|
||
# 设置视频处理的最大像素限制
|
||
export VIDEO_MAX_PIXELS=100000000
|
||
|
||
# 运行程序
|
||
./vision_process_example
|
||
```
|
||
|
||
### 常量配置
|
||
```cpp
|
||
// 可在头文件中修改的常量
|
||
static constexpr int IMAGE_FACTOR = 28; // 图像尺寸因子
|
||
static constexpr int MIN_PIXELS = 4 * 28 * 28; // 图像最小像素
|
||
static constexpr int MAX_PIXELS = 16384 * 28 * 28; // 图像最大像素
|
||
static constexpr int MAX_RATIO = 200; // 最大宽高比
|
||
|
||
static constexpr int VIDEO_MIN_PIXELS = 128 * 28 * 28; // 视频最小像素
|
||
static constexpr int VIDEO_MAX_PIXELS = 768 * 28 * 28; // 视频最大像素
|
||
static constexpr int FRAME_FACTOR = 2; // 帧数因子
|
||
static constexpr double FPS = 2.0; // 默认帧率
|
||
```
|
||
|
||
## 🧪 测试
|
||
|
||
运行示例程序：
|
||
```bash
|
||
# 编译后运行测试
|
||
./build/test/vision_process_example
|
||
|
||
# 或者使用CMake测试
|
||
cd build
|
||
ctest
|
||
```
|
||
|
||
## 🐛 错误处理
|
||
|
||
库使用标准C++异常处理机制：
|
||
|
||
```cpp
|
||
try {
|
||
auto result = processor.fetchImage(config);
|
||
// 处理结果
|
||
} catch (const std::invalid_argument& e) {
|
||
std::cerr << "参数错误: " << e.what() << std::endl;
|
||
} catch (const std::runtime_error& e) {
|
||
std::cerr << "运行时错误: " << e.what() << std::endl;
|
||
} catch (const std::exception& e) {
|
||
std::cerr << "未知错误: " << e.what() << std::endl;
|
||
}
|
||
```
|
||
|
||
### 常见错误类型
|
||
- `std::invalid_argument`: 参数错误或配置无效
|
||
- `std::runtime_error`: 文件读取、网络请求或处理失败
|
||
- `cv::Exception`: OpenCV相关错误
|
||
|
||
## 🚀 性能优化
|
||
|
||
### 内存管理
|
||
- 使用RAII自动管理内存
|
||
- 预分配向量容量减少重分配
|
||
- 及时释放大型Mat对象
|
||
|
||
### 处理优化
|
||
- 批量处理多个文件时重用processor实例
|
||
- 对于大视频文件，考虑分段处理
|
||
- 使用多线程处理多个独立任务
|
||
|
||
### 示例：批量处理优化
|
||
```cpp
|
||
VisionProcessor processor; // 重用实例
|
||
|
||
for (const auto& config : imageConfigs) {
|
||
try {
|
||
auto image = processor.fetchImage(config);
|
||
// 处理图像...
|
||
} catch (const std::exception& e) {
|
||
// 记录错误但继续处理其他图像
|
||
std::cerr << "跳过图像: " << e.what() << std::endl;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交Issue和Pull Request！
|
||
|
||
### 开发设置
|
||
```bash
|
||
# 克隆仓库
|
||
git clone <repository-url>
|
||
cd project-root
|
||
|
||
# 创建开发分支
|
||
git checkout -b feature/your-feature
|
||
|
||
# 编译并测试
|
||
mkdir build && cd build
|
||
cmake -DCMAKE_BUILD_TYPE=Debug ..
|
||
make
|
||
./test/vision_process_example
|
||
```
|
||
|
||
## 📄 许可证
|
||
|
||
本项目基于原始Qwen多模态Python代码改编，请遵循相应的开源许可证条款。
|
||
|
||
## 🆘 常见问题
|
||
|
||
### Q: 编译时找不到OpenCV
|
||
A: 确保安装了OpenCV开发包，或使用`-DOpenCV_DIR`指定路径。
|
||
|
||
### Q: libcurl链接错误
|
||
A: 安装libcurl开发包：`sudo apt-get install libcurl4-openssl-dev`
|
||
|
||
### Q: 视频文件无法打开
|
||
A: 确保OpenCV编译时启用了相应的视频编解码器支持。
|
||
|
||
### Q: 内存使用过高
|
||
A: 对于大文件，考虑降低max_pixels设置或分批处理。
|
||
|
||
### Q: Base64解码失败
|
||
A: 确保Base64字符串格式正确，包含正确的MIME类型前缀。
|
||
|
||
---
|
||
|
||
**🌟 如果这个项目对您有帮助，请给我们一个Star！**
|
||
|
||
### Qwen2VLProcessor 类
|
||
|
||
#### 主要方法
|
||
|
||
| 方法 | 说明 | 返回值 |
|
||
|------|------|--------|
|
||
| `operator()` | 主处理方法，处理多模态输入 | `BatchFeature` |
|
||
| `getNumMultimodalTokens()` | 计算多模态token数量 | `MultiModalData` |
|
||
| `batchDecode()` | 批量解码token序列 | `std::vector<std::string>` |
|
||
| `decode()` | 解码单个token序列 | `std::string` |
|
||
| `postProcessImageTextToText()` | 后处理生成的文本 | `std::vector<std::string>` |
|
||
| `getModelInputNames()` | 获取模型输入名称 | `std::vector<std::string>` |
|
||
|
||
#### 支持的数据结构
|
||
|
||
```cpp
|
||
// 批处理特征结构
|
||
struct BatchFeature {
|
||
std::map<std::string, std::vector<std::vector<int>>> data;
|
||
std::string tensor_type;
|
||
};
|
||
|
||
// 多模态数据信息
|
||
struct MultiModalData {
|
||
std::optional<std::vector<int>> num_image_tokens;
|
||
std::optional<std::vector<int>> num_image_patches;
|
||
std::optional<std::vector<int>> num_video_tokens;
|
||
std::optional<std::vector<int>> num_video_patches;
|
||
};
|
||
|
||
// 处理器配置参数
|
||
struct ProcessorKwargs {
|
||
std::map<std::string, std::string> images_kwargs;
|
||
std::map<std::string, std::string> videos_kwargs;
|
||
std::map<std::string, std::string> text_kwargs;
|
||
};
|
||
```
|
||
|
||
#### 抽象接口
|
||
|
||
如需自定义处理器，需要实现以下抽象接口：
|
||
|
||
```cpp
|
||
class ImageProcessor {
|
||
public:
|
||
virtual std::map<std::string, std::vector<std::vector<int>>> processImages(
|
||
const ImageInput& images,
|
||
const std::map<std::string, std::string>& kwargs) = 0;
|
||
virtual int getMergeSize() const = 0;
|
||
virtual int getNumberOfImagePatches(int height, int width,
|
||
const std::map<std::string, std::string>& kwargs) const = 0;
|
||
virtual std::vector<std::string> getModelInputNames() const = 0;
|
||
};
|
||
|
||
class VideoProcessor {
|
||
public:
|
||
virtual std::map<std::string, std::vector<std::vector<int>>> processVideos(
|
||
const VideoInput& videos,
|
||
const std::map<std::string, std::string>& kwargs) = 0;
|
||
virtual int getMergeSize() const = 0;
|
||
virtual int getNumberOfVideoPatches(int num_frames, int height, int width,
|
||
const std::map<std::string, std::string>& kwargs) const = 0;
|
||
};
|
||
|
||
class Tokenizer {
|
||
public:
|
||
virtual std::map<std::string, std::vector<std::vector<int>>> tokenize(
|
||
const std::vector<std::string>& texts,
|
||
const std::map<std::string, std::string>& kwargs) = 0;
|
||
virtual std::vector<std::string> batchDecode(
|
||
const std::vector<std::vector<int>>& token_ids,
|
||
bool skip_special_tokens = true,
|
||
bool clean_up_tokenization_spaces = false) = 0;
|
||
virtual std::string decode(
|
||
const std::vector<int>& token_ids,
|
||
bool skip_special_tokens = true,
|
||
bool clean_up_tokenization_spaces = false) = 0;
|
||
virtual int convertTokensToIds(const std::string& token) = 0;
|
||
virtual std::vector<std::string> getModelInputNames() const = 0;
|
||
};
|
||
```
|
||
|
||
#### 工具函数 |