VideoAgentTrek Screen Filter插件开发：为Ollama平台添加视频过滤能力

VideoAgentTrek Screen Filter插件开发：为Ollama平台添加视频过滤能力

最近在折腾视频处理项目时，发现Ollama生态里虽然文本和图片模型很丰富，但专门处理视频的插件还不多。正好手头有个基于VideoAgentTrek的屏幕内容过滤模型，我就琢磨着能不能把它打包成一个Ollama Mod，让其他开发者也能一键拉取、直接使用。

这个想法其实挺实用的。想象一下，你只需要在Ollama里执行一条简单的命令，就能获得一个具备视频分析能力的服务，可以直接处理本地视频文件或者网络视频流，自动过滤掉无关的屏幕内容，只保留你关心的核心信息区域。无论是做内容审核、教育视频处理，还是自动化办公，都能省下不少功夫。

今天这篇教程，我就来手把手带你走一遍整个流程。从理解Ollama Modfile的格式开始，到如何把模型权重和推理脚本打包进去，再到定义清晰易用的输入输出接口，最后在星图GPU上完成构建和测试。整个过程下来，你会发现给Ollama生态添砖加瓦并没有想象中那么复杂。

1. 环境准备与项目初始化

在开始编写Mod之前，我们需要先把开发环境搭建好，并理解一下Ollama Mod的基本结构。

1.1 开发环境要求

为了顺利完成这个插件开发，你需要准备以下环境：

• Ollama环境：确保你的机器上已经安装了Ollama。如果还没装，可以去Ollama官网下载对应操作系统的安装包，安装过程很简单，基本上就是一路下一步。
• Python环境：建议使用Python 3.8或更高版本。我们这个插件主要用Python来写推理逻辑。
• 基础工具：需要安装git用于版本控制，以及docker（或者podman）用于构建Mod镜像。如果你打算在星图GPU上构建，这些工具星图环境通常都预装好了。
• 模型文件：准备好训练好的VideoAgentTrek Screen Filter模型权重文件。如果你还没有，可以先用一个简单的示例模型来测试流程。

1.2 创建项目目录结构

一个好的目录结构能让后续开发更清晰。我建议按下面的方式来组织你的项目文件：

videoagent-screen-filter-mod/ ├── Modfile ├── README.md ├── app.py ├── requirements.txt ├── models/ │ └── screen_filter.pth └── utils/ ├── video_processor.py └── filter_logic.py

我来简单解释一下每个文件的作用：

• Modfile：这是Ollama Mod的核心配置文件，相当于这个插件的“说明书”，告诉Ollama怎么构建和运行它。
• app.py：主程序入口，里面包含了处理请求的HTTP服务逻辑。
• requirements.txt：列出项目依赖的Python包。
• models/：存放模型权重文件的目录。
• utils/：放一些工具函数，比如视频处理、过滤逻辑等。

你可以用下面的命令快速创建这个结构：

mkdir -p videoagent-screen-filter-mod/{models,utils} cd videoagent-screen-filter-mod touch Modfile README.md app.py requirements.txt touch utils/video_processor.py utils/filter_logic.py

2. 编写Ollama Modfile配置文件

Modfile是Ollama Mod的灵魂，它定义了插件的元数据、构建步骤和运行方式。我们来一步步把它写出来。

2.1 基础信息定义

打开Modfile，我们先从最基础的信息开始写起：

# 基础镜像，选择包含Python和常用深度学习库的镜像 FROM ollama/mod-base:py3.10-cuda11.8 # 设置维护者信息 LABEL maintainer="your-email@example.com" # 设置工作目录 WORKDIR /app # 设置环境变量 ENV PYTHONUNBUFFERED=1 ENV MODEL_PATH=/app/models/screen_filter.pth

这里有几个关键点需要注意：

1. 基础镜像选择：我选了ollama/mod-base:py3.10-cuda11.8，这个镜像已经预装了Python 3.10和CUDA 11.8，省去了我们安装底层依赖的麻烦。如果你的模型需要特定版本的CUDA，可以换用其他tag。
2. 工作目录：统一设置为/app，这样所有的代码和模型都放在这个目录下，结构清晰。
3. 环境变量：MODEL_PATH定义了模型文件的路径，这样在代码里就可以通过环境变量来引用，而不是硬编码。

2.2 依赖安装与文件复制

接下来，我们需要安装Python依赖，并把项目文件复制到镜像中：

# 复制依赖文件并安装 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt && \ rm -rf /root/.cache/pip # 复制模型文件 COPY models/ /app/models/ # 复制应用代码 COPY utils/ /app/utils/ COPY app.py /app/

这里我用了--no-cache-dir参数来减少镜像大小，安装完成后还清理了pip缓存。模型文件和应用代码分开复制，这样如果只更新代码而不更新模型时，Docker可以更好地利用缓存。

2.3 定义服务入口

最后，我们需要告诉Ollama这个Mod怎么启动：

# 暴露服务端口（Ollama Mod标准端口是11434） EXPOSE 11434 # 设置健康检查 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \ CMD curl -f http://localhost:11434/ || exit 1 # 启动命令 CMD ["python", "app.py"]

健康检查是个好习惯，它能让Ollama知道你的服务是否正常运行。这里设置每30秒检查一次，如果连续3次失败，容器会被标记为不健康。

3. 实现核心推理逻辑

配置文件写好了，现在我们来写实际的代码。先从最简单的依赖文件开始。

3.1 定义项目依赖

在requirements.txt里，列出所有需要的Python包：

torch>=1.12.0 torchvision>=0.13.0 opencv-python>=4.7.0 numpy>=1.21.0 pillow>=9.0.0 fastapi>=0.95.0 uvicorn>=0.21.0 pydantic>=1.10.0 requests>=2.28.0

这些包涵盖了深度学习框架、图像处理、Web服务等核心功能。版本号我给了最低要求，你可以根据实际情况调整。

3.2 编写视频处理工具

在utils/video_processor.py里，我们实现视频读取和预处理的功能：

import cv2 import numpy as np from typing import Generator, Optional import requests from io import BytesIO class VideoProcessor: """视频处理器，支持本地文件和网络URL""" def __init__(self, max_frame_size: tuple = (640, 480)): self.max_frame_size = max_frame_size def read_video(self, video_source: str) -> Generator[np.ndarray, None, None]: """ 读取视频帧 Args: video_source: 视频源，可以是本地文件路径或网络URL Yields: 处理后的视频帧 """ # 判断是本地文件还是网络URL if video_source.startswith(('http://', 'https://')): # 处理网络视频 response = requests.get(video_source, stream=True) if response.status_code != 200: raise ValueError(f"无法获取视频: {video_source}") # 将视频内容保存到临时文件 temp_file = BytesIO(response.content) # 这里需要根据实际视频格式处理 # 简化示例：假设是MP4格式 cap = cv2.VideoCapture(video_source) else: # 处理本地文件 cap = cv2.VideoCapture(video_source) if not cap.isOpened(): raise ValueError(f"无法打开视频: {video_source}") try: while True: ret, frame = cap.read() if not ret: break # 调整帧大小 frame = self._resize_frame(frame) # 转换颜色空间（如果需要） frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) yield frame finally: cap.release() def _resize_frame(self, frame: np.ndarray) -> np.ndarray: """调整帧大小""" height, width = frame.shape[:2] max_width, max_height = self.max_frame_size if width > max_width or height > max_height: scale = min(max_width / width, max_height / height) new_width = int(width * scale) new_height = int(height * scale) frame = cv2.resize(frame, (new_width, new_height)) return frame def extract_key_frames(self, video_source: str, interval: int = 10) -> list: """ 提取关键帧 Args: video_source: 视频源 interval: 帧间隔 Returns: 关键帧列表 """ frames = [] for i, frame in enumerate(self.read_video(video_source)): if i % interval == 0: frames.append(frame) return frames

这个类做了几件事：

1. 统一处理本地文件和网络URL两种输入方式
2. 自动调整视频帧大小，避免内存溢出
3. 提供了提取关键帧的功能，这在处理长视频时很有用

3.3 实现过滤逻辑

在utils/filter_logic.py里，我们实现核心的屏幕内容过滤算法：

import torch import numpy as np from PIL import Image import torchvision.transforms as transforms from typing import List, Tuple class ScreenFilter: """屏幕内容过滤器""" def __init__(self, model_path: str): """ 初始化过滤器 Args: model_path: 模型权重文件路径 """ self.device = torch.device('cuda' if torch.cuda.is_available() else 'cpu') self.model = self._load_model(model_path) self.model.eval() # 定义图像预处理 self.transform = transforms.Compose([ transforms.Resize((224, 224)), transforms.ToTensor(), transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]) ]) def _load_model(self, model_path: str): """ 加载模型 注意：这里需要根据你的实际模型结构来实现 这里只是一个示例 """ # 示例：加载一个简单的分类模型 # 实际使用时需要替换为你的VideoAgentTrek模型 try: # 这里假设模型是一个PyTorch模型 model = torch.load(model_path, map_location=self.device) return model except Exception as e: print(f"加载模型失败: {e}") # 返回一个简单的示例模型 return self._create_dummy_model() def _create_dummy_model(self): """创建示例模型（用于测试）""" class DummyModel(torch.nn.Module): def __init__(self): super().__init__() self.conv = torch.nn.Conv2d(3, 16, kernel_size=3, padding=1) self.pool = torch.nn.AdaptiveAvgPool2d((1, 1)) self.fc = torch.nn.Linear(16, 2) def forward(self, x): x = torch.relu(self.conv(x)) x = self.pool(x) x = x.view(x.size(0), -1) return self.fc(x) return DummyModel() def filter_screen_content(self, frame: np.ndarray) -> dict: """ 过滤单帧图像中的屏幕内容 Args: frame: 输入图像帧 Returns: 过滤结果，包含感兴趣区域和置信度 """ # 转换numpy数组为PIL图像 pil_image = Image.fromarray(frame) # 预处理 input_tensor = self.transform(pil_image).unsqueeze(0).to(self.device) # 推理 with torch.no_grad(): output = self.model(input_tensor) probabilities = torch.softmax(output, dim=1) # 解析结果 # 这里需要根据你的模型输出格式来调整 confidence = probabilities[0][1].item() # 假设第二类是"包含屏幕内容" # 示例：简单的区域检测（实际应该用模型输出的区域） height, width = frame.shape[:2] regions = [] if confidence > 0.5: # 检测到屏幕内容，返回一个示例区域 regions.append({ 'bbox': [width//4, height//4, 3*width//4, 3*height//4], 'confidence': confidence, 'label': 'screen_content' }) return { 'has_screen': confidence > 0.5, 'confidence': confidence, 'regions': regions, 'frame_size': {'width': width, 'height': height} } def process_video(self, video_source: str, frame_interval: int = 10) -> dict: """ 处理整个视频 Args: video_source: 视频源 frame_interval: 帧间隔 Returns: 视频处理结果 """ from .video_processor import VideoProcessor processor = VideoProcessor() frames = processor.extract_key_frames(video_source, frame_interval) results = [] for i, frame in enumerate(frames): result = self.filter_screen_content(frame) result['frame_index'] = i * frame_interval results.append(result) # 汇总结果 screen_frames = [r for r in results if r['has_screen']] return { 'total_frames': len(frames), 'screen_frames': len(screen_frames), 'screen_ratio': len(screen_frames) / len(frames) if frames else 0, 'detailed_results': results, 'video_source': video_source }

这个类封装了完整的过滤逻辑：

1. 加载训练好的模型
2. 对单帧图像进行屏幕内容检测
3. 提供批量处理视频的接口
4. 返回结构化的结果，包括检测区域、置信度等

4. 构建Web服务接口

现在我们需要创建一个Web服务，让Ollama能够通过HTTP请求来调用我们的功能。

4.1 定义数据模型

首先在app.py的开头，我们定义请求和响应的数据格式：

from fastapi import FastAPI, HTTPException from pydantic import BaseModel, HttpUrl from typing import Optional, List, Dict, Any import os import sys # 添加utils目录到Python路径 sys.path.append(os.path.join(os.path.dirname(__file__), 'utils')) from utils.filter_logic import ScreenFilter from utils.video_processor import VideoProcessor # 定义请求模型 class VideoFilterRequest(BaseModel): """视频过滤请求""" video_url: Optional[HttpUrl] = None video_path: Optional[str] = None frame_interval: int = 10 threshold: float = 0.5 class Config: schema_extra = { "example": { "video_url": "https://example.com/video.mp4", "frame_interval": 10, "threshold": 0.5 } } # 定义响应模型 class RegionInfo(BaseModel): """区域信息""" bbox: List[int] # [x1, y1, x2, y2] confidence: float label: str class FrameResult(BaseModel): """单帧结果""" frame_index: int has_screen: bool confidence: float regions: List[RegionInfo] frame_size: Dict[str, int] class VideoFilterResponse(BaseModel): """视频过滤响应""" success: bool message: str data: Optional[Dict[str, Any]] = None error: Optional[str] = None class Config: schema_extra = { "example": { "success": True, "message": "视频处理完成", "data": { "total_frames": 100, "screen_frames": 45, "screen_ratio": 0.45, "video_source": "https://example.com/video.mp4", "detailed_results": [] } } }

这里用了Pydantic来定义数据模型，好处是自动验证输入数据，还能生成漂亮的API文档。

4.2 创建FastAPI应用

接下来创建FastAPI应用并设置路由：

# 创建FastAPI应用 app = FastAPI( title="VideoAgentTrek Screen Filter", description="基于VideoAgentTrek的屏幕内容过滤Ollama Mod", version="1.0.0" ) # 全局变量 screen_filter = None @app.on_event("startup") async def startup_event(): """应用启动时加载模型""" global screen_filter try: model_path = os.getenv("MODEL_PATH", "/app/models/screen_filter.pth") screen_filter = ScreenFilter(model_path) print(f"模型加载成功: {model_path}") except Exception as e: print(f"模型加载失败: {e}") # 即使模型加载失败，也创建一个示例过滤器用于测试 screen_filter = ScreenFilter("") @app.get("/") async def root(): """根路径，返回服务信息""" return { "service": "VideoAgentTrek Screen Filter", "version": "1.0.0", "status": "running", "endpoints": { "health": "/health", "filter": "/filter", "docs": "/docs" } } @app.get("/health") async def health_check(): """健康检查接口""" return {"status": "healthy", "model_loaded": screen_filter is not None}

启动时自动加载模型，这样服务一启动就准备好处理请求了。健康检查接口让Ollama知道服务是否正常。

4.3 实现核心过滤接口

最重要的部分来了——实现视频过滤的接口：

@app.post("/filter", response_model=VideoFilterResponse) async def filter_video(request: VideoFilterRequest): """ 处理视频过滤请求 支持两种输入方式： 1. video_url: 网络视频URL 2. video_path: 本地视频文件路径 至少需要提供一种视频源 """ # 验证输入 if not request.video_url and not request.video_path: raise HTTPException( status_code=400, detail="必须提供video_url或video_path" ) try: # 确定视频源 video_source = request.video_url or request.video_path # 处理视频 result = screen_filter.process_video( str(video_source), frame_interval=request.frame_interval ) # 应用阈值过滤 if request.threshold != 0.5: # 默认阈值是0.5 filtered_results = [] for frame_result in result['detailed_results']: frame_result['has_screen'] = frame_result['confidence'] > request.threshold # 过滤区域 frame_result['regions'] = [ region for region in frame_result['regions'] if region['confidence'] > request.threshold ] filtered_results.append(frame_result) # 重新计算统计信息 screen_frames = [r for r in filtered_results if r['has_screen']] result['screen_frames'] = len(screen_frames) result['screen_ratio'] = len(screen_frames) / len(filtered_results) if filtered_results else 0 result['detailed_results'] = filtered_results return VideoFilterResponse( success=True, message="视频处理完成", data=result ) except Exception as e: return VideoFilterResponse( success=False, message="视频处理失败", error=str(e) ) @app.post("/filter/frame") async def filter_single_frame(frame_data: dict): """ 处理单帧图像 用于测试或实时处理场景 """ try: # 这里需要根据实际输入格式解析帧数据 # 示例：假设输入是base64编码的图像 import base64 from io import BytesIO if 'image_base64' in frame_data: image_data = base64.b64decode(frame_data['image_base64']) image = Image.open(BytesIO(image_data)) frame = np.array(image) else: raise ValueError("需要提供image_base64字段") result = screen_filter.filter_screen_content(frame) return { "success": True, "result": result } except Exception as e: raise HTTPException(status_code=500, detail=str(e))

这个接口设计得比较灵活：

1. 同时支持网络URL和本地文件路径
2. 可以调整帧采样间隔，平衡处理速度和精度
3. 可以设置置信度阈值，控制过滤的严格程度
4. 返回详细的结果，包括每一帧的检测情况

4.4 添加实用工具接口

为了方便使用，我们再添加几个辅助接口：

@app.get("/info") async def get_model_info(): """获取模型信息""" if screen_filter is None: raise HTTPException(status_code=503, detail="模型未加载") return { "model_name": "VideoAgentTrek Screen Filter", "input_types": ["video_url", "video_path", "image_base64"], "output_types": ["screen_detection", "region_bbox", "confidence_score"], "supported_formats": ["mp4", "avi", "mov", "webm"], "max_resolution": "1920x1080", "version": "1.0.0" } @app.post("/batch") async def batch_process(requests: List[VideoFilterRequest]): """ 批量处理多个视频 适用于需要处理大量视频的场景 """ results = [] for i, request in enumerate(requests): try: result = await filter_video(request) results.append({ "index": i, "success": result.success, "data": result.data if result.success else None, "error": result.error }) except Exception as e: results.append({ "index": i, "success": False, "error": str(e) }) return { "total": len(requests), "successful": sum(1 for r in results if r["success"]), "failed": sum(1 for r in results if not r["success"]), "results": results } if __name__ == "__main__": import uvicorn uvicorn.run(app, host="0.0.0.0", port=11434)

5. 构建与测试Mod

代码都写好了，现在我们来构建这个Mod并进行测试。

5.1 构建Ollama Mod

在项目根目录下，执行构建命令：

# 构建Mod（给Mod起个名字，比如videoagent-screen-filter） ollama mod create videoagent-screen-filter . # 或者如果你已经配置了Modfile，可以直接用docker构建 docker build -t videoagent-screen-filter .

构建过程可能会花一些时间，特别是第一次构建时需要下载基础镜像。构建成功后，你可以看到类似这样的输出：

Successfully built xxxxxxxxxxxx Successfully tagged videoagent-screen-filter:latest

5.2 本地测试

构建完成后，先在本地测试一下：

# 运行Mod docker run -p 11434:11434 videoagent-screen-filter # 或者用Ollama运行 ollama run videoagent-screen-filter

服务启动后，打开浏览器访问http://localhost:11434/docs，你应该能看到自动生成的API文档。可以在这里直接测试接口。

用curl测试一下健康检查：

curl http://localhost:11434/health

应该返回：

{"status":"healthy","model_loaded":true}

5.3 测试视频过滤功能

现在测试核心功能。准备一个测试视频（可以是本地文件，也可以是一个公开的网络视频URL），然后发送请求：

# 测试本地视频文件 curl -X POST "http://localhost:11434/filter" \ -H "Content-Type: application/json" \ -d '{ "video_path": "/path/to/your/test.mp4", "frame_interval": 10, "threshold": 0.5 }' # 或者测试网络视频 curl -X POST "http://localhost:11434/filter" \ -H "Content-Type: application/json" \ -d '{ "video_url": "https://example.com/sample.mp4", "frame_interval": 5, "threshold": 0.7 }'

如果一切正常，你会收到一个详细的JSON响应，包含视频中屏幕内容的检测结果。

5.4 在星图GPU上构建和测试

如果你的模型比较大，或者需要GPU加速，可以在星图GPU环境上构建和运行：

# 登录星图容器服务 # （这里假设你已经配置好了星图环境） # 构建支持GPU的镜像 docker build -t your-registry/videoagent-screen-filter:gpu . # 推送到镜像仓库 docker push your-registry/videoagent-screen-filter:gpu # 在星图GPU节点上运行 # 需要配置相应的部署文件，这里以Kubernetes为例 kubectl apply -f deployment.yaml

deployment.yaml示例：

apiVersion: apps/v1 kind: Deployment metadata: name: videoagent-screen-filter spec: replicas: 1 selector: matchLabels: app: videoagent-screen-filter template: metadata: labels: app: videoagent-screen-filter spec: containers: - name: filter image: your-registry/videoagent-screen-filter:gpu ports: - containerPort: 11434 resources: limits: nvidia.com/gpu: 1 env: - name: MODEL_PATH value: "/app/models/screen_filter.pth" --- apiVersion: v1 kind: Service metadata: name: videoagent-screen-filter-service spec: selector: app: videoagent-screen-filter ports: - port: 80 targetPort: 11434

6. 发布与使用

6.1 完善文档

在发布之前，我们需要完善README.md文件，让其他用户知道怎么使用这个Mod：

# VideoAgentTrek Screen Filter for Ollama 一个基于VideoAgentTrek的屏幕内容过滤Ollama Mod，可以自动检测视频中的屏幕区域。 ## 功能特性 - 🎥 支持本地视频文件和网络视频URL - 🔍 自动检测屏幕内容区域 - ⚡ 可配置的帧采样间隔 - 📊 返回详细的检测结果和统计信息 - 🐳 一键部署，开箱即用 ## 快速开始 ### 安装 ```bash # 从Ollama Mod仓库安装 ollama mod install videoagent-screen-filter # 或者从本地构建 ollama mod create videoagent-screen-filter . ``` ### 使用示例 ```python import requests import json # 准备请求数据 data = { "video_url": "https://example.com/sample.mp4", "frame_interval": 10, "threshold": 0.6 } # 发送请求 response = requests.post( "http://localhost:11434/filter", json=data ) # 处理结果 result = response.json() if result["success"]: print(f"检测到屏幕内容的帧数: {result['data']['screen_frames']}") print(f"屏幕内容比例: {result['data']['screen_ratio']:.2%}") ``` ## API文档 启动服务后访问 `http://localhost:11434/docs` 查看完整的API文档。 ## 配置参数 - `frame_interval`: 帧采样间隔（默认10） - `threshold`: 置信度阈值（默认0.5） - `video_url`: 网络视频URL - `video_path`: 本地视频文件路径 ## 许可证 MIT

6.2 发布到Ollama Mod仓库

如果你希望分享给更多人使用，可以考虑发布到Ollama Mod仓库：

1. 准备发布包：

   # 确保所有文件都在正确的位置 # 清理不必要的文件 rm -rf __pycache__ *.pyc # 创建发布压缩包 tar -czvf videoagent-screen-filter.tar.gz .

2. 提交到Git仓库（如果使用Git管理）：

   git add . git commit -m "发布VideoAgentTrek Screen Filter v1.0.0" git tag v1.0.0 git push origin main --tags

3. 按照Ollama Mod发布流程提交你的Mod。

6.3 实际使用场景

这个Mod可以在很多场景下使用：

1. 在线教育平台：自动检测教学视频中的PPT或代码界面，方便快速定位重点内容。
2. 内容审核：识别视频中是否包含屏幕录制内容，用于版权保护或内容分类。
3. 视频编辑辅助：自动标记视频中的屏幕区域，方便后续编辑或特效添加。
4. 会议记录：从会议录像中提取屏幕共享部分，生成重点摘要。

7. 总结

走完这一整套流程，你应该已经掌握了如何为Ollama平台开发一个视频处理插件。从最初的Modfile编写，到核心推理逻辑的实现，再到Web服务的搭建，最后完成构建和测试，每一步都是实际开发中会遇到的问题。

这个VideoAgentTrek Screen Filter Mod虽然是个示例，但框架是完整的。你可以基于这个框架，替换成自己的视频处理模型，比如动作识别、场景分割、目标跟踪等等。Ollama的Mod机制真的很灵活，只要遵循基本的接口规范，几乎可以封装任何类型的AI能力。

在实际使用中，你可能会遇到一些性能优化的问题，比如视频处理比较耗时，或者内存占用较高。这时候可以考虑添加一些优化策略，比如支持视频流式处理、添加结果缓存、支持分布式处理等。不过对于大多数应用场景，这个基础版本已经足够用了。

如果你在开发过程中遇到问题，或者有改进的想法，欢迎一起交流。毕竟开源生态的魅力就在于大家互相学习、共同完善。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。