一句话让 AI 把视频剪好这不是宣传片里才会出现的场景。Grok Bot 智能体就是一个把“自然语言指令”和“视频剪辑工具链”接起来的项目形态你输入一句中文比如“把 inputs/demo.mp4 裁剪出前 30 秒”系统先让大模型解析出要执行的操作、作用在哪个文件、参数是什么再把这些参数拼成 FFmpeg 命令去实际处理视频。整个过程覆盖裁剪、转码、拼接、字幕附加和素材目录整理最终还能对外提供 HTTP API接入自动化流程。先给结论。这套 Grok Bot 智能体实现具备下面几个特点用自然语言直接下达剪辑指令不需要打开 Premiere 手动拖时间轴。核心工具是 FFmpeg单机 CPU 就能跑不强制要求高端显卡。支持按目录批量扫描一次处理多个视频素材。对外暴露 REST API方便接到自己的项目或运维脚本里。大模型层可替换用第三方接口或本地模型都可以。本文会带你从环境准备开始依次完成安装部署、功能测试、接口调用和批量任务最后还会给出常见问题和排查思路。如果你平时接触视频素材整理或者正在做 LLM 工具调用这类智能体项目这篇内容可以直接收藏。1. Grok Bot 智能体核心能力速览先把核心能力用一张表列清楚方便快速判断要不要继续往下看。项目类型自然语言驱动的视频处理智能体LLM 意图解析 FFmpeg 工具调用主要功能视频裁剪、转码、拼接、字幕导入、素材目录整理交互方式中文或英文自然语言指令批量任务支持扫描输入目录后按队列处理API 能力支持可封装为 REST API启动方式Python 命令行 / FastAPI 服务 / 智能体平台硬件门槛基础流程 CPU 可运行本地大模型推理或 GPU 转码需额外配置显存占用使用第三方模型接口时无硬性要求本地模型时取决于模型大小适合读者视频创作者、自动化运维、智能体开发者这套设计的核心不是重新实现视频编解码而是把“用户说话”翻译成“可执行工具参数”。大模型负责理解用户意图FFmpeg 负责执行视频操作中间用一个 JSON 结构把两边衔接起来。这也是目前大部分 Agent 类项目的基础范式。2. 适用场景与使用边界Grok Bot 智能体最合适的场景是那些重复度高、规则清晰的视频处理任务。举例来说一批 4K 视频需要统一转成 720p 上传到内部平台。把所有素材的前 30 秒预览片段抽取出来做自动样片。把多个片段按顺序拼接成一个长视频。把分散在不同目录的素材按日期、分辨率、时长自动归档。这些任务如果交给人工操作耗时且容易出错。交给 Grok Bot 智能体后只需要把指令写清楚它会自动匹配文件、生成 FFmpeg 命令、执行处理并返回结果。但也要明确边界。这个方案不适合做高度创意化的剪辑比如复杂转场、关键帧调色、多轨道混音这些仍然需要专业剪辑工具和人工微调。它适合的是“批量执行、规则明确、结果可检查”的处理流程。合规方面需要特别注意。视频素材可能涉及版权、肖像、声音等敏感信息处理前必须确认来源合法并已获得授权。不要用这个智能体去处理来源不明的视频不要批量剪辑他人受版权保护的素材更不要在未授权的情况下对自然人肖像和音色做二次加工。商用前要对生成结果做人工复核避免输出带来法律风险。3. Grok Bot 智能体本地部署环境准备这一步不需要很复杂但环境不对会浪费大量时间。先列一个通用检查清单。3.1 基础依赖依赖项建议要求用途操作系统Windows 10、Linux、macOS运行环境Python3.10 及以上编写智能体逻辑FFmpeg5.x 及以上加入 PATH视频处理核心工具大模型服务OpenAI 兼容接口或 Ollama 等本地模型意图解析端口默认 8000可调整FastAPI 服务监听3.2 检查本机环境先确认 Python 和 FFmpeg 是否可用。python --version ffmpeg -version如果 FFmpeg 提示找不到需要先安装 FFmpeg并把它所在目录加入系统 PATH。Windows 用户可以在终端里手动配置环境变量Linux 用户可以用包管理器安装。3.3 创建项目目录建议目录结构如下模型文件、输入素材、输出结果分开存放。grok_bot/ ├── app.py # FastAPI 入口 ├── core.py # 视频工具与任务执行 ├── agent.py # 大模型意图解析 ├── requirements.txt # Python 依赖 ├── .env # 模型服务配置 ├── inputs/ # 输入素材目录 └── outputs/ # 输出结果目录3.4 安装 Python 依赖创建requirements.txt写入以下内容fastapi uvicorn openai python-dotenv pydantic安装pip install -r requirements.txt如果网络环境受限可以换用国内 pip 镜像源例如pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple3.5 模型服务配置在.env文件中写入模型服务地址和模型名称。LLM_API_KEYyour_api_key LLM_BASE_URLhttps://your-model-service-url/v1 LLM_MODELyour-model-name如果你使用本地模型且提供 OpenAI 兼容接口可以把LLM_BASE_URL配置为本地服务地址例如LLM_BASE_URLhttp://127.0.0.1:11434/v1 LLM_MODELqwen2.5:7b这里不用固定到某个厂商。只要模型服务兼容 OpenAI 的 Chat Completions 格式Grok Bot 智能体就能接进去。常用的大模型平台基本都支持这种接口格式。4. 安装部署与启动方式这里给出两套启动路径。第一套是纯 Python 命令启动适合快速测试第二套是 FastAPI 服务启动适合接入业务系统。如果你不想写代码也可以考虑 Dify、Coze 等智能体平台。4.1 编写视频工具层在core.py中写一组操作 FFmpeg 的封装函数。核心目标是让上层调用不用关心命令行细节。import subprocess import os import shutil def run_cmd(cmd): 执行命令行并返回日志 result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: raise RuntimeError(f命令执行失败: { .join(cmd)}\n{result.stderr}) return result.stdout def cut_video(input_path, output_path, start0, durationNone): cmd [ffmpeg, -i, input_path, -ss, str(start)] if duration: cmd [-t, str(duration)] cmd [-c, copy, output_path, -y] run_cmd(cmd) def transcode_video(input_path, output_path, height720): cmd [ ffmpeg, -i, input_path, -vf, fscale-2:{height}, -c:v, libx264, -preset, fast, -c:a, aac, -b:a, 128k, output_path, -y ] run_cmd(cmd) def concat_videos(file_list_path, output_path): cmd [ ffmpeg, -f, concat, -safe, 0, -i, file_list_path, -c, copy, output_path, -y ] run_cmd(cmd) def organize_file(src_path, dest_dir): 把素材移动到指定目录 os.makedirs(dest_dir, exist_okTrue) shutil.move(src_path, os.path.join(dest_dir, os.path.basename(src_path)))这里每个函数都对应一种工具能力后续智能体只根据大模型解析出的结果调用对应函数。4.2 编写意图解析层在agent.py中通过大模型把自然语言指令解析成固定结构的 JSON。import json import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(LLM_API_KEY, local-key), base_urlos.getenv(LLM_BASE_URL, http://127.0.0.1:11434/v1) ) SYSTEM_PROMPT 你是视频处理智能体。用户会输入一句剪辑或整理视频的中文指令。 请只输出 JSON不要输出任何解释。JSON 结构如下 { tool: cut | transcode | concat | organize, params: { input: 输入文件或目录, output: 输出文件或目录, start: 0, duration: 30, height: 720, dest_dir: 目标目录 } } 注意tool 只能是 cut、transcode、concat、organize 中的一个。 def parse_instruction(instruction: str) - dict: 把自然语言指令解析为结构化 JSON response client.chat.completions.create( modelos.getenv(LLM_MODEL, your-model), messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: instruction} ], temperature0 ) text response.choices[0].message.content # 兼容模型输出带 json 代码块的情况 if json in text: text text.strip().removeprefix(json).removesuffix() return json.loads(text)温度设置为 0可以减少模型输出的随机性。要求模型只输出 JSON也是为了让后续解析更稳定。如果模型输出带代码块标记代码里做一次清理。4.3 编写 FastAPI 服务入口在app.py中提供 HTTP API。import os from fastapi import FastAPI from pydantic import BaseModel from agent import parse_instruction from core import cut_video, transcode_video, concat_videos, organize_file app FastAPI() class ProcessRequest(BaseModel): instruction: str input_dir: str ./inputs output_dir: str ./outputs def execute_tool(parsed: dict, input_dir: str, output_dir: str): 根据 JSON 参数执行对应工具 tool parsed[tool] params parsed[params] input_path params.get(input, ) if not os.path.isabs(input_path): input_path os.path.join(input_dir, input_path) output_path params.get(output, ) if not os.path.isabs(output_path): output_path os.path.join(output_dir, output_path) if tool cut: cut_video( input_path, output_path, startparams.get(start, 0), durationparams.get(duration) ) return [output_path] if tool transcode: transcode_video( input_path, output_path, heightparams.get(height, 720) ) return [output_path] if tool concat: file_list_path params[file_list] concat_videos(file_list_path, output_path) return [output_path] if tool organize: organize_file(input_path, params.get(dest_dir, output_dir)) return [output_path] raise ValueError(f不支持的 tool 类型: {tool}) app.post(/api/process) async def process_video(req: ProcessRequest): parsed parse_instruction(req.instruction) files execute_tool(parsed, req.input_dir, req.output_dir) return {status: success, files: files} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)4.4 启动服务在项目根目录执行uvicorn app:app --host 0.0.0.0 --port 8000启动后终端会出现类似Uvicorn running on http://0.0.0.0:8000的日志。浏览器访问http://127.0.0.1:8000/docs可以直接看到 Swagger 接口文档页面。如果端口被占用换一个端口再启动uvicorn app:app --host 127.0.0.1 --port 80015. Grok Bot 智能体功能测试与效果验证这一阶段建议按“小样本 - 多场景 - 批量”的顺序来。先用一个文件测试确认流程通了再扩展到整个目录。5.1 测试用例设计测试编号指令预期结果T01把 inputs/demo.mp4 裁剪出前 30 秒输出一个 30 秒的视频文件T02把 inputs/demo.mov 转为 720p MP4输出 720p、H.264 编码的 MP4 文件T03合并 inputs/a.mp4 和 inputs/b.mp4输出一个拼接后的视频文件T04把 inputs/4k/ 目录下所有视频移动到 outputs/4k/文件完成归档5.2 用 curl 触发测试启动服务后在另一个终端执行curl -X POST http://127.0.0.1:8000/api/process \ -H Content-Type: application/json \ -d { instruction: 把 inputs/demo.mp4 裁剪出前 30 秒, input_dir: ., output_dir: outputs }预期返回{ status: success, files: [outputs/demo_30s.mp4] }然后去outputs目录查看生成的文件用播放器打开确认时长接近 30 秒。5.3 测试转码和目录整理假设inputs目录下有一个source.mov执行curl -X POST http://127.0.0.1:8000/api/process \ -H Content-Type: application/json \ -d { instruction: 把 inputs/source.mov 转成 720p MP4, input_dir: ., output_dir: outputs }判断成功标准返回结果包含outputs/source.mp4。使用ffprobe查看编码信息确认分辨率高度为 720。检查命令ffprobe outputs/source.mp4如果看到Video: h264、720x1280这样的信息说明转码成功。5.4 失败时的排查优先级测试失败时先看服务端终端日志。常见的情况依次是大模型返回的 JSON 解析失败说明模型没有严格按照 system prompt 输出需要优化提示词。FFmpeg 命令执行报错说明参数不对或源文件编码有问题。文件路径带中文或特殊字符导致命令解析异常需要统一使用绝对路径。6. 接口 API 调用与批量任务设计接口层不止是单次调用。真实场景里用户更关心能不能一次处理一批文件怎么在后台跑失败了怎么重试。6.1 API 请求参数说明参数类型必填说明instructionstring是自然语言指令input_dirstring否输入素材目录默认 ./inputsoutput_dirstring否输出结果目录默认 ./outputs6.2 Python 客户端调用示例import requests url http://127.0.0.1:8000/api/process payload { instruction: 把 inputs 目录下所有 mp4 转为 720p, input_dir: ./inputs, output_dir: ./outputs } response requests.post(url, jsonpayload, timeout120) print(response.json())注意单次请求如果处理大量视频同步接口会阻塞较长时间。如果视频文件大、任务多建议改成异步任务队列。6.3 简化版异步任务队列在app.py中增加任务队列让接口先返回task_id后台线程再执行处理。import uuid from queue import Queue job_queue Queue() jobs {} def worker_loop(): while True: job_id, instruction, input_dir, output_dir job_queue.get() try: parsed parse_instruction(instruction) files execute_tool(parsed, input_dir, output_dir) jobs[job_id] {status: success, files: files} except Exception as exc: jobs[job_id] {status: failed, error: str(exc)} finally: job_queue.task_done() import threading threading.Thread(targetworker_loop, daemonTrue).start() app.post(/api/process/async) async def process_video_async(req: ProcessRequest): job_id str(uuid.uuid4()) jobs[job_id] {status: pending} job_queue.put((job_id, req.instruction, req.input_dir, req.output_dir)) return {task_id: job_id} app.get(/api/status/{job_id}) async def get_status(job_id: str): return jobs.get(job_id, {status: not_found})提交异步任务curl -X POST http://127.0.0.1:8000/api/process/async \ -H Content-Type: application/json \ -d { instruction: 把 ./inputs 下面所有 mov 转成 mp4, input_dir: ./inputs, output_dir: ./outputs }返回{ task_id: 5f6b8a92-d4c3-4e1e-8fe6-0cc649d4799b }查询状态curl http://127.0.0.1:8000/api/status/5f6b8a92-d4c3-4e1e-8fe6-0cc649d4799b返回success后再去输出目录确认生成的文件。异步队列能避免大批量任务把接口阻塞死也能给前端一个轮询状态。6.4 批量任务的注意点批量处理时建议先做一个“预扫描”让智能体先把目录里的文件名、大小、编码信息列出来再决定执行哪些命令。这样可以避免对不存在的文件直接执行 FFmpeg减少无效任务。预扫描可以用ffprobe来完成这一步可以作为独立工具函数写入core.py。7. 资源占用与性能观察视频处理是典型的资源密集型任务。Grok Bot 智能体的资源占用主要分成两部分大模型推理和 FFmpeg 视频处理。7.1 大模型推理占用如果用的是第三方模型 API本机基本不消耗额外算力只需要网络请求和 JSON 解析。这种情况下延迟一般在 1 到 3 秒具体取决于模型服务本身。如果使用本地模型显存占用取决于模型参数大小。7B 量级的模型可能需要 6G 到 8G 显存更大模型会更高。实际占用需要以本机测试为准不建议在没有实测的情况下直接按某个数值去规划服务器资源。7.2 FFmpeg 转码占用FFmpeg 的 CPU 占用非常直接转码时多核 CPU 会持续高负载裁剪时如果使用-c copy参数不重新编码速度很快CPU 占用也低转码到 H.264 则不同它需要重新编码每一帧CPU 占用会接近满载。资源观察建议Linux 使用top或htop查看 CPU 和内存占用。有 NVIDIA 显卡时使用nvidia-smi查看 GPU 使用率和显存。Windows 使用任务管理器查看性能页。7.3 如何降低负载先给一批小文件测试确认命令和参数正确再跑全量任务。批量任务并发数不要太激进默认单线程处理后续再根据服务器负载调整并发量。如果服务器有 NVIDIA 显卡FFmpeg 可以把编码器换成h264_nvencffmpeg -i input.mp4 -c:v h264_nvenc -preset p4 -c:a aac output.mp4这样可以把转码负载从 CPU 转移到 GPU但需要提前确认显卡驱动和驱动版本支持该编码器。不同显卡支持的编码器不完全一样需要在当前环境实测。8. 常见问题与排查方法问题现象可能原因排查方式解决方案启动服务时端口被占用8000 端口已被其他进程占用netstat -ano | findstr 8000改用其他端口启动ffmpeg 命令找不到FFmpeg 未安装或未加入 PATH终端执行ffmpeg -version重新安装 FFmpeg 并配置环境变量大模型返回解析失败模型没有按 system prompt 输出 JSON打开接口日志查看返回原文优化提示词增加少量示例中文路径乱码终端编码和 Python 编码不一致打印日志检查路径字符统一使用 UTF-8路径转绝对路径API 调用超时视频文件过大或模型服务响应慢缩短输入文件或换小分辨率测试增加超时时间改用异步任务批量任务中途卡住某个文件损坏或 FFmpeg 命令等待输入查看任务队列日志定位失败任务给子进程增加超时和失败重试转码后没有声音输入音频编码格式不兼容用 ffprobe 查看输入流信息在转码命令中显式指定音频编码器生成文件大小为 0FFmpeg 命令因参数错误直接被终止查看子进程错误日志检查源文件路径和输出目录权限一句经验所有排查先看日志日志里最核心的是大模型返回原文和 FFmpeg 的 stderr 输出。只要这两个地方能看到实际信息绝大多数问题都能定位。9. 最佳实践与使用建议Grok Bot 智能体这种“自然语言 工具调用”的设计落地时要注意的不是模型能力而是工程稳定性。9.1 先跑干模式给 FFmpeg 执行层加一个--dry-run开关。启动后先只打印命令不真正执行。这样能快速验证意图解析是否准确而不用每次错误都消耗视频处理时间。DRY_RUN True # 测试阶段建议开启 def execute_tool(parsed, input_dir, output_dir, dry_runDRY_RUN): if dry_run: print(f[DRY_RUN] tool{parsed[tool]} params{parsed[params]}) return [] # 实际执行……9.2 限制可执行工具白名单不要让大模型随意构造 shell 命令。只在系统里暴露cut_video、transcode_video、concat_videos、organize_file这几个工具函数不允许模型直接执行任意命令行。这是安全边界也需要在 system prompt 里写死。9.3 输出文件命名规范在core.py中给输出文件加时间戳或任务 ID避免重名覆盖。例如import time def make_output_name(source_name): ts time.strftime(%Y%m%d_%H%M%S) stem os.path.splitext(os.path.basename(source_name))[0] return f{stem}_{ts}.mp4这样在批量处理时每次执行的结果都不容易互相覆盖。9.4 日志与审计记录每个任务的完整信息任务 ID、用户指令、解析后的 JSON、实际执行命令、输出文件、耗时、执行结果。一旦出问题可以通过日志回放整个执行链路。import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(grok_bot) logger.info(task%s instruction%s parsed%s, job_id, instruction, parsed)9.5 合规与授权处理视频前确认素材来源合法。涉及人物肖像、声音、商标、版权内容时必须获得相应授权。商用项目还要在系统里保留授权记录和审批日志。涉及换脸、声音克隆等敏感能力时强烈建议不要开放给普通用户避免被滥用。10. 总结与下一步Grok Bot 智能体的价值不在于把 FFmpeg 命令包装成函数而在于把“人的语言”转换成“机器的操作参数”。对于有大量重复剪辑需求的内容团队这种工具能把原本几小时的体力活压缩成一条指令。如果你要上手最先应该验证的是基础裁剪和转码这两个场景。它们逻辑简单出问题时容易定位。之后再做批量目录扫描和异步任务队列这两个功能会让整个方案从“能跑”变成“能用”。最容易踩的坑有两个一是大模型没有按格式输出 JSON导致解析直接爆炸二是 FFmpeg 参数写错导致处理到一半任务挂掉。这两个问题都需要在设计和测试阶段就做好兜底。后续可以扩展的方向也很明确接上语音识别自动生成字幕加入视频分类和标签系统让智能体自己维护一个素材索引库或者和其他智能体平台配合形成多智能体流水线。一句话完成视频剪辑这才刚刚开始。 一句话让AI剪视频：Grok Bot智能体实战指南
一句话让 AI 把视频剪好这不是宣传片里才会出现的场景。Grok Bot 智能体就是一个把“自然语言指令”和“视频剪辑工具链”接起来的项目形态你输入一句中文比如“把 inputs/demo.mp4 裁剪出前 30 秒”系统先让大模型解析出要执行的操作、作用在哪个文件、参数是什么再把这些参数拼成 FFmpeg 命令去实际处理视频。整个过程覆盖裁剪、转码、拼接、字幕附加和素材目录整理最终还能对外提供 HTTP API接入自动化流程。先给结论。这套 Grok Bot 智能体实现具备下面几个特点用自然语言直接下达剪辑指令不需要打开 Premiere 手动拖时间轴。核心工具是 FFmpeg单机 CPU 就能跑不强制要求高端显卡。支持按目录批量扫描一次处理多个视频素材。对外暴露 REST API方便接到自己的项目或运维脚本里。大模型层可替换用第三方接口或本地模型都可以。本文会带你从环境准备开始依次完成安装部署、功能测试、接口调用和批量任务最后还会给出常见问题和排查思路。如果你平时接触视频素材整理或者正在做 LLM 工具调用这类智能体项目这篇内容可以直接收藏。1. Grok Bot 智能体核心能力速览先把核心能力用一张表列清楚方便快速判断要不要继续往下看。项目类型自然语言驱动的视频处理智能体LLM 意图解析 FFmpeg 工具调用主要功能视频裁剪、转码、拼接、字幕导入、素材目录整理交互方式中文或英文自然语言指令批量任务支持扫描输入目录后按队列处理API 能力支持可封装为 REST API启动方式Python 命令行 / FastAPI 服务 / 智能体平台硬件门槛基础流程 CPU 可运行本地大模型推理或 GPU 转码需额外配置显存占用使用第三方模型接口时无硬性要求本地模型时取决于模型大小适合读者视频创作者、自动化运维、智能体开发者这套设计的核心不是重新实现视频编解码而是把“用户说话”翻译成“可执行工具参数”。大模型负责理解用户意图FFmpeg 负责执行视频操作中间用一个 JSON 结构把两边衔接起来。这也是目前大部分 Agent 类项目的基础范式。2. 适用场景与使用边界Grok Bot 智能体最合适的场景是那些重复度高、规则清晰的视频处理任务。举例来说一批 4K 视频需要统一转成 720p 上传到内部平台。把所有素材的前 30 秒预览片段抽取出来做自动样片。把多个片段按顺序拼接成一个长视频。把分散在不同目录的素材按日期、分辨率、时长自动归档。这些任务如果交给人工操作耗时且容易出错。交给 Grok Bot 智能体后只需要把指令写清楚它会自动匹配文件、生成 FFmpeg 命令、执行处理并返回结果。但也要明确边界。这个方案不适合做高度创意化的剪辑比如复杂转场、关键帧调色、多轨道混音这些仍然需要专业剪辑工具和人工微调。它适合的是“批量执行、规则明确、结果可检查”的处理流程。合规方面需要特别注意。视频素材可能涉及版权、肖像、声音等敏感信息处理前必须确认来源合法并已获得授权。不要用这个智能体去处理来源不明的视频不要批量剪辑他人受版权保护的素材更不要在未授权的情况下对自然人肖像和音色做二次加工。商用前要对生成结果做人工复核避免输出带来法律风险。3. Grok Bot 智能体本地部署环境准备这一步不需要很复杂但环境不对会浪费大量时间。先列一个通用检查清单。3.1 基础依赖依赖项建议要求用途操作系统Windows 10、Linux、macOS运行环境Python3.10 及以上编写智能体逻辑FFmpeg5.x 及以上加入 PATH视频处理核心工具大模型服务OpenAI 兼容接口或 Ollama 等本地模型意图解析端口默认 8000可调整FastAPI 服务监听3.2 检查本机环境先确认 Python 和 FFmpeg 是否可用。python --version ffmpeg -version如果 FFmpeg 提示找不到需要先安装 FFmpeg并把它所在目录加入系统 PATH。Windows 用户可以在终端里手动配置环境变量Linux 用户可以用包管理器安装。3.3 创建项目目录建议目录结构如下模型文件、输入素材、输出结果分开存放。grok_bot/ ├── app.py # FastAPI 入口 ├── core.py # 视频工具与任务执行 ├── agent.py # 大模型意图解析 ├── requirements.txt # Python 依赖 ├── .env # 模型服务配置 ├── inputs/ # 输入素材目录 └── outputs/ # 输出结果目录3.4 安装 Python 依赖创建requirements.txt写入以下内容fastapi uvicorn openai python-dotenv pydantic安装pip install -r requirements.txt如果网络环境受限可以换用国内 pip 镜像源例如pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple3.5 模型服务配置在.env文件中写入模型服务地址和模型名称。LLM_API_KEYyour_api_key LLM_BASE_URLhttps://your-model-service-url/v1 LLM_MODELyour-model-name如果你使用本地模型且提供 OpenAI 兼容接口可以把LLM_BASE_URL配置为本地服务地址例如LLM_BASE_URLhttp://127.0.0.1:11434/v1 LLM_MODELqwen2.5:7b这里不用固定到某个厂商。只要模型服务兼容 OpenAI 的 Chat Completions 格式Grok Bot 智能体就能接进去。常用的大模型平台基本都支持这种接口格式。4. 安装部署与启动方式这里给出两套启动路径。第一套是纯 Python 命令启动适合快速测试第二套是 FastAPI 服务启动适合接入业务系统。如果你不想写代码也可以考虑 Dify、Coze 等智能体平台。4.1 编写视频工具层在core.py中写一组操作 FFmpeg 的封装函数。核心目标是让上层调用不用关心命令行细节。import subprocess import os import shutil def run_cmd(cmd): 执行命令行并返回日志 result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: raise RuntimeError(f命令执行失败: { .join(cmd)}\n{result.stderr}) return result.stdout def cut_video(input_path, output_path, start0, durationNone): cmd [ffmpeg, -i, input_path, -ss, str(start)] if duration: cmd [-t, str(duration)] cmd [-c, copy, output_path, -y] run_cmd(cmd) def transcode_video(input_path, output_path, height720): cmd [ ffmpeg, -i, input_path, -vf, fscale-2:{height}, -c:v, libx264, -preset, fast, -c:a, aac, -b:a, 128k, output_path, -y ] run_cmd(cmd) def concat_videos(file_list_path, output_path): cmd [ ffmpeg, -f, concat, -safe, 0, -i, file_list_path, -c, copy, output_path, -y ] run_cmd(cmd) def organize_file(src_path, dest_dir): 把素材移动到指定目录 os.makedirs(dest_dir, exist_okTrue) shutil.move(src_path, os.path.join(dest_dir, os.path.basename(src_path)))这里每个函数都对应一种工具能力后续智能体只根据大模型解析出的结果调用对应函数。4.2 编写意图解析层在agent.py中通过大模型把自然语言指令解析成固定结构的 JSON。import json import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(LLM_API_KEY, local-key), base_urlos.getenv(LLM_BASE_URL, http://127.0.0.1:11434/v1) ) SYSTEM_PROMPT 你是视频处理智能体。用户会输入一句剪辑或整理视频的中文指令。 请只输出 JSON不要输出任何解释。JSON 结构如下 { tool: cut | transcode | concat | organize, params: { input: 输入文件或目录, output: 输出文件或目录, start: 0, duration: 30, height: 720, dest_dir: 目标目录 } } 注意tool 只能是 cut、transcode、concat、organize 中的一个。 def parse_instruction(instruction: str) - dict: 把自然语言指令解析为结构化 JSON response client.chat.completions.create( modelos.getenv(LLM_MODEL, your-model), messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: instruction} ], temperature0 ) text response.choices[0].message.content # 兼容模型输出带 json 代码块的情况 if json in text: text text.strip().removeprefix(json).removesuffix() return json.loads(text)温度设置为 0可以减少模型输出的随机性。要求模型只输出 JSON也是为了让后续解析更稳定。如果模型输出带代码块标记代码里做一次清理。4.3 编写 FastAPI 服务入口在app.py中提供 HTTP API。import os from fastapi import FastAPI from pydantic import BaseModel from agent import parse_instruction from core import cut_video, transcode_video, concat_videos, organize_file app FastAPI() class ProcessRequest(BaseModel): instruction: str input_dir: str ./inputs output_dir: str ./outputs def execute_tool(parsed: dict, input_dir: str, output_dir: str): 根据 JSON 参数执行对应工具 tool parsed[tool] params parsed[params] input_path params.get(input, ) if not os.path.isabs(input_path): input_path os.path.join(input_dir, input_path) output_path params.get(output, ) if not os.path.isabs(output_path): output_path os.path.join(output_dir, output_path) if tool cut: cut_video( input_path, output_path, startparams.get(start, 0), durationparams.get(duration) ) return [output_path] if tool transcode: transcode_video( input_path, output_path, heightparams.get(height, 720) ) return [output_path] if tool concat: file_list_path params[file_list] concat_videos(file_list_path, output_path) return [output_path] if tool organize: organize_file(input_path, params.get(dest_dir, output_dir)) return [output_path] raise ValueError(f不支持的 tool 类型: {tool}) app.post(/api/process) async def process_video(req: ProcessRequest): parsed parse_instruction(req.instruction) files execute_tool(parsed, req.input_dir, req.output_dir) return {status: success, files: files} if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)4.4 启动服务在项目根目录执行uvicorn app:app --host 0.0.0.0 --port 8000启动后终端会出现类似Uvicorn running on http://0.0.0.0:8000的日志。浏览器访问http://127.0.0.1:8000/docs可以直接看到 Swagger 接口文档页面。如果端口被占用换一个端口再启动uvicorn app:app --host 127.0.0.1 --port 80015. Grok Bot 智能体功能测试与效果验证这一阶段建议按“小样本 - 多场景 - 批量”的顺序来。先用一个文件测试确认流程通了再扩展到整个目录。5.1 测试用例设计测试编号指令预期结果T01把 inputs/demo.mp4 裁剪出前 30 秒输出一个 30 秒的视频文件T02把 inputs/demo.mov 转为 720p MP4输出 720p、H.264 编码的 MP4 文件T03合并 inputs/a.mp4 和 inputs/b.mp4输出一个拼接后的视频文件T04把 inputs/4k/ 目录下所有视频移动到 outputs/4k/文件完成归档5.2 用 curl 触发测试启动服务后在另一个终端执行curl -X POST http://127.0.0.1:8000/api/process \ -H Content-Type: application/json \ -d { instruction: 把 inputs/demo.mp4 裁剪出前 30 秒, input_dir: ., output_dir: outputs }预期返回{ status: success, files: [outputs/demo_30s.mp4] }然后去outputs目录查看生成的文件用播放器打开确认时长接近 30 秒。5.3 测试转码和目录整理假设inputs目录下有一个source.mov执行curl -X POST http://127.0.0.1:8000/api/process \ -H Content-Type: application/json \ -d { instruction: 把 inputs/source.mov 转成 720p MP4, input_dir: ., output_dir: outputs }判断成功标准返回结果包含outputs/source.mp4。使用ffprobe查看编码信息确认分辨率高度为 720。检查命令ffprobe outputs/source.mp4如果看到Video: h264、720x1280这样的信息说明转码成功。5.4 失败时的排查优先级测试失败时先看服务端终端日志。常见的情况依次是大模型返回的 JSON 解析失败说明模型没有严格按照 system prompt 输出需要优化提示词。FFmpeg 命令执行报错说明参数不对或源文件编码有问题。文件路径带中文或特殊字符导致命令解析异常需要统一使用绝对路径。6. 接口 API 调用与批量任务设计接口层不止是单次调用。真实场景里用户更关心能不能一次处理一批文件怎么在后台跑失败了怎么重试。6.1 API 请求参数说明参数类型必填说明instructionstring是自然语言指令input_dirstring否输入素材目录默认 ./inputsoutput_dirstring否输出结果目录默认 ./outputs6.2 Python 客户端调用示例import requests url http://127.0.0.1:8000/api/process payload { instruction: 把 inputs 目录下所有 mp4 转为 720p, input_dir: ./inputs, output_dir: ./outputs } response requests.post(url, jsonpayload, timeout120) print(response.json())注意单次请求如果处理大量视频同步接口会阻塞较长时间。如果视频文件大、任务多建议改成异步任务队列。6.3 简化版异步任务队列在app.py中增加任务队列让接口先返回task_id后台线程再执行处理。import uuid from queue import Queue job_queue Queue() jobs {} def worker_loop(): while True: job_id, instruction, input_dir, output_dir job_queue.get() try: parsed parse_instruction(instruction) files execute_tool(parsed, input_dir, output_dir) jobs[job_id] {status: success, files: files} except Exception as exc: jobs[job_id] {status: failed, error: str(exc)} finally: job_queue.task_done() import threading threading.Thread(targetworker_loop, daemonTrue).start() app.post(/api/process/async) async def process_video_async(req: ProcessRequest): job_id str(uuid.uuid4()) jobs[job_id] {status: pending} job_queue.put((job_id, req.instruction, req.input_dir, req.output_dir)) return {task_id: job_id} app.get(/api/status/{job_id}) async def get_status(job_id: str): return jobs.get(job_id, {status: not_found})提交异步任务curl -X POST http://127.0.0.1:8000/api/process/async \ -H Content-Type: application/json \ -d { instruction: 把 ./inputs 下面所有 mov 转成 mp4, input_dir: ./inputs, output_dir: ./outputs }返回{ task_id: 5f6b8a92-d4c3-4e1e-8fe6-0cc649d4799b }查询状态curl http://127.0.0.1:8000/api/status/5f6b8a92-d4c3-4e1e-8fe6-0cc649d4799b返回success后再去输出目录确认生成的文件。异步队列能避免大批量任务把接口阻塞死也能给前端一个轮询状态。6.4 批量任务的注意点批量处理时建议先做一个“预扫描”让智能体先把目录里的文件名、大小、编码信息列出来再决定执行哪些命令。这样可以避免对不存在的文件直接执行 FFmpeg减少无效任务。预扫描可以用ffprobe来完成这一步可以作为独立工具函数写入core.py。7. 资源占用与性能观察视频处理是典型的资源密集型任务。Grok Bot 智能体的资源占用主要分成两部分大模型推理和 FFmpeg 视频处理。7.1 大模型推理占用如果用的是第三方模型 API本机基本不消耗额外算力只需要网络请求和 JSON 解析。这种情况下延迟一般在 1 到 3 秒具体取决于模型服务本身。如果使用本地模型显存占用取决于模型参数大小。7B 量级的模型可能需要 6G 到 8G 显存更大模型会更高。实际占用需要以本机测试为准不建议在没有实测的情况下直接按某个数值去规划服务器资源。7.2 FFmpeg 转码占用FFmpeg 的 CPU 占用非常直接转码时多核 CPU 会持续高负载裁剪时如果使用-c copy参数不重新编码速度很快CPU 占用也低转码到 H.264 则不同它需要重新编码每一帧CPU 占用会接近满载。资源观察建议Linux 使用top或htop查看 CPU 和内存占用。有 NVIDIA 显卡时使用nvidia-smi查看 GPU 使用率和显存。Windows 使用任务管理器查看性能页。7.3 如何降低负载先给一批小文件测试确认命令和参数正确再跑全量任务。批量任务并发数不要太激进默认单线程处理后续再根据服务器负载调整并发量。如果服务器有 NVIDIA 显卡FFmpeg 可以把编码器换成h264_nvencffmpeg -i input.mp4 -c:v h264_nvenc -preset p4 -c:a aac output.mp4这样可以把转码负载从 CPU 转移到 GPU但需要提前确认显卡驱动和驱动版本支持该编码器。不同显卡支持的编码器不完全一样需要在当前环境实测。8. 常见问题与排查方法问题现象可能原因排查方式解决方案启动服务时端口被占用8000 端口已被其他进程占用netstat -ano | findstr 8000改用其他端口启动ffmpeg 命令找不到FFmpeg 未安装或未加入 PATH终端执行ffmpeg -version重新安装 FFmpeg 并配置环境变量大模型返回解析失败模型没有按 system prompt 输出 JSON打开接口日志查看返回原文优化提示词增加少量示例中文路径乱码终端编码和 Python 编码不一致打印日志检查路径字符统一使用 UTF-8路径转绝对路径API 调用超时视频文件过大或模型服务响应慢缩短输入文件或换小分辨率测试增加超时时间改用异步任务批量任务中途卡住某个文件损坏或 FFmpeg 命令等待输入查看任务队列日志定位失败任务给子进程增加超时和失败重试转码后没有声音输入音频编码格式不兼容用 ffprobe 查看输入流信息在转码命令中显式指定音频编码器生成文件大小为 0FFmpeg 命令因参数错误直接被终止查看子进程错误日志检查源文件路径和输出目录权限一句经验所有排查先看日志日志里最核心的是大模型返回原文和 FFmpeg 的 stderr 输出。只要这两个地方能看到实际信息绝大多数问题都能定位。9. 最佳实践与使用建议Grok Bot 智能体这种“自然语言 工具调用”的设计落地时要注意的不是模型能力而是工程稳定性。9.1 先跑干模式给 FFmpeg 执行层加一个--dry-run开关。启动后先只打印命令不真正执行。这样能快速验证意图解析是否准确而不用每次错误都消耗视频处理时间。DRY_RUN True # 测试阶段建议开启 def execute_tool(parsed, input_dir, output_dir, dry_runDRY_RUN): if dry_run: print(f[DRY_RUN] tool{parsed[tool]} params{parsed[params]}) return [] # 实际执行……9.2 限制可执行工具白名单不要让大模型随意构造 shell 命令。只在系统里暴露cut_video、transcode_video、concat_videos、organize_file这几个工具函数不允许模型直接执行任意命令行。这是安全边界也需要在 system prompt 里写死。9.3 输出文件命名规范在core.py中给输出文件加时间戳或任务 ID避免重名覆盖。例如import time def make_output_name(source_name): ts time.strftime(%Y%m%d_%H%M%S) stem os.path.splitext(os.path.basename(source_name))[0] return f{stem}_{ts}.mp4这样在批量处理时每次执行的结果都不容易互相覆盖。9.4 日志与审计记录每个任务的完整信息任务 ID、用户指令、解析后的 JSON、实际执行命令、输出文件、耗时、执行结果。一旦出问题可以通过日志回放整个执行链路。import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(grok_bot) logger.info(task%s instruction%s parsed%s, job_id, instruction, parsed)9.5 合规与授权处理视频前确认素材来源合法。涉及人物肖像、声音、商标、版权内容时必须获得相应授权。商用项目还要在系统里保留授权记录和审批日志。涉及换脸、声音克隆等敏感能力时强烈建议不要开放给普通用户避免被滥用。10. 总结与下一步Grok Bot 智能体的价值不在于把 FFmpeg 命令包装成函数而在于把“人的语言”转换成“机器的操作参数”。对于有大量重复剪辑需求的内容团队这种工具能把原本几小时的体力活压缩成一条指令。如果你要上手最先应该验证的是基础裁剪和转码这两个场景。它们逻辑简单出问题时容易定位。之后再做批量目录扫描和异步任务队列这两个功能会让整个方案从“能跑”变成“能用”。最容易踩的坑有两个一是大模型没有按格式输出 JSON导致解析直接爆炸二是 FFmpeg 参数写错导致处理到一半任务挂掉。这两个问题都需要在设计和测试阶段就做好兜底。后续可以扩展的方向也很明确接上语音识别自动生成字幕加入视频分类和标签系统让智能体自己维护一个素材索引库或者和其他智能体平台配合形成多智能体流水线。一句话完成视频剪辑这才刚刚开始。