爆款结构迁移引擎 — 技术架构与协议文档文档性质项目技术说明文档适用读者架构师、后端开发工程师、安全审计工程师、系统集成工程师目录第一部分整体AI架构1.1 系统概述1.2 架构拓扑1.3 核心组件与模块划分1.4 全链路数据流1.5 关键技术栈1.6 组件间交互关系第二部分工具协议2.1 API 设计规范2.2 数据交换格式定义2.3 接口调用流程与状态机2.4 LLM 通信协议2.5 配置文件规范第三部分安全边界3.1 数据安全策略3.2 访问控制与身份认证3.3 加密方案与密钥管理3.4 输入验证与注入防护3.5 安全风险评估矩阵3.6 安全配置最佳实践第一部分整体AI架构1.1 系统概述爆款结构迁移引擎是一个基于大语言模型LLM驱动的全栈AI视频创作平台。系统采用前后端分离的 B/S 架构以FastAPI 异步 Web 服务为后端枢纽集成云端的Doubao-Seed-2.0-lite大模型作为核心推理引擎辅以OpenCV 本地视频分析管线打通样例视频上传 → LLM 结构拆解 → LLM 缺口识别 → LLM 时间线编译 → 导出/预览的全链路闭环。业务目标阶段输入处理引擎输出① 样例解析爆款视频文件MP4/MOVOpenCV 管线sample_datafps/时长/分辨率/关键帧/镜头切换点② 结构分析sample_data压缩后Doubao-Seed-2.0-litestructure_template脚本/节奏/包装三重结构③ 缺口识别目标主题 已有素材清单Doubao-Seed-2.0-litegap_analysisidentified_gaps槽位清单④ 时间线编译结构模板 缺口分析 版本类型Doubao-Seed-2.0-liteSVT-JSON 视频时间线⑤ 输出SVT-JSON—浏览器下载 / 弹窗预览1.2 架构拓扑┌─────────────────────────────────────────────────────────────────────────┐ │ 用户浏览器 (User Agent) │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ frontend/index.html (SPA: TailwindCSS Marked.js) │ │ │ │ upload-sample │ analyze-structure │ identify-gaps │ generate-svt│ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ HTTP/HTTPS (fetch) │ └────────────────────────────────┼────────────────────────────────────────┘ │ ┌────────────────────────────────┼────────────────────────────────────────┐ │ 应用服务器层 (FastAPI) │ │ ┌─────────────────────────────┴────────────────────────────────────┐ │ │ │ backend/main.py │ │ │ │ CORS 中间件 │ 9个 RESTful 端点 │ 全局异常捕获 │ │ │ └───────┬──────────────────┬──────────────────┬─────────────────────┘ │ │ │ │ │ │ │ ┌───────▼─────────┐ ┌──────▼──────┐ ┌───────▼────────────┐ │ │ │ video_processor │ │ llm_client │ │ gap_completion │ │ │ │ (OpenCV) │ │ () │ │ (策略引擎) │ │ │ └─────────────────┘ └──────┬───────┘ └────────────────────┘ │ │ │ │ │ ┌─────────▼──────────┐ │ │ │ config.py │ │ │ │ (YAML 环境变量) │ │ │ └────────────────────┘ │ └──────────────────────────────┼──────────────────────────────────────────┘ │ HTTPS (OpenAI-compatible API) ┌──────────────────────────────┼──────────────────────────────────────────┐ │ 云服务 (VolcEngine Ark) │ │ ┌───────────────────────────▼──────────────────────────────────┐ │ │ │ POST /api/v3/chat/completions │ │ │ │ Provider: volcengine | Model: ep-* │ │ │ │ 认证: Bearer Token (api_key) │ │ │ └──────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘部署拓扑说明单进程部署main.py→uvicorn.run(backend.main:app, host0.0.0.0, port8000, reloadTrue)前端通过文件协议 (file://) 或静态托管打开frontend/index.html通过fetch连接后端后端可直接访问互联网调用API无需额外代理1.3 核心组件与模块划分模块依赖关系图main.py (启动入口) └── backend/ ├── main.py ← 依赖 → config.py, video_processor, llm_client, gap_completion ├── config.py ← 无内部依赖仅依赖 yaml / os ├── video_processor.py ← 无内部依赖仅依赖 cv2 / numpy ├── llm_client.py ← 依赖 → config.py │ ├── VolcEngineLLMClient ← HTTP 客户端封装 │ ├── DoubaoSeed2LiteEngine ← 业务语义层 │ ├── fix_incomplete_json() ← JSON 修复引擎 │ ├── normalize_*() ← 智能归一化引擎 │ └── compact_*() ← 数据压缩工具 └── gap_completion.py ← 依赖 → llm_client.py └── GapCompletionEngine ← 策略补全 多版本生成各模块详细职责1.3.1main.py— 服务启动入口属性值框架Uvicorn ASGI Server监听0.0.0.0:8000热重载reloadTrue入口uvicorn.run(backend.main:app, ...)关键行为通过sys.path.insert将项目根目录加入 Python 路径以backend.main:app模块路径启动FastAPI app 实例1.3.2backend/config.py— 全局配置管理设计模式YAML 持久化 环境变量覆盖层次化优先级配置优先级链环境变量 config.yaml 默认硬编码值配置项一览配置键YAML 路径环境变量默认值用途SECRET_KEYsecret_keySECRET_KEYyour-secret-key-here应用签名密钥DEBUGdebugDEBUGtrue调试模式开关VOLCENGINE_API_KEYvolcengine.api_keyVOLCENGINE_API_KEYAPI KeyBearer TokenVOLCENGINE_BASE_URLvolcengine.base_urlVOLCENGINE_BASE_URLAPI基础地址DOUBAO_SEED_2_LITE_MODEL_EPdoubao_seed_2_lite.model_epDOUBAO_SEED_2_LITE_MODEL_EPDoubao-Seed-2.0-lite 的 Endpoint IDLLM_TIMEOUTllm_timeoutLLM_TIMEOUT120LLM API 调用超时秒MAX_FILE_SIZE— 硬编码—500 * 1024 * 1024(500MB)最大上传文件大小UPLOAD_DIR— 硬编码—{BASE_DIR}/uploads/上传文件存储目录自动创建OUTPUT_DIR— 硬编码—{BASE_DIR}/outputs/输出结果目录自动创建TEMP_DIR— 硬编码—{BASE_DIR}/temp/临时文件目录自动创建YAML 加载流程① 读取 {BASE_DIR}/config.yaml ② yaml.safe_load() 反序列化 ③ 读取失败则降级为空 dict仅使用环境变量 ④ Settings 类属性初始化时统一执行 os.getenv() → yaml_config 降级链 ⑤ UPLOAD_DIR / OUTPUT_DIR / TEMP_DIR 自动 mkdir1.3.3backend/video_processor.py— 视频解析引擎属性值技术OpenCV 4.8.1cv2运行位置本地 CPU非云端实例化全局单例VideoProcessor()核心方法方法输入输出算法extract_basic_info()Path(视频文件路径){fps, duration, total_frames, resolution, width, height}cv2.VideoCapture逐属性读取extract_key_frames()Path,num_frames10List[str](Base64 JPEG)numpy.linspace均匀采样 →cv2.imencode(.jpg)detect_shot_changes()Path,threshold30.0List[float](切换时间点)逐帧灰度直方图比对cv2.HISTCMP_CORREL差异 threshold时记录镜头切换process_sample_video()Path{basic_info, key_frames, shot_changes, estimated_script}编排调用上述三个方法附加预估 Hook/Body/CTA 三段时间分配建议性能特征关键帧提取O(n)均匀采样固定 10 帧镜头检测O(n)逐帧比对30fps 视频每秒处理约 10-15 帧Base64 编码开销关键帧 Base64 编码直接嵌入 JSON 返回对前端透明1.3.4backend/llm_client.py— LLM 服务对接层核心模块本模块是系统的最核心组件包含两个类 四个辅助引擎A.VolcEngineLLMClient— HTTP 客户端封装对OpenAI-compatible API的异步 HTTP 调用属性值协议HTTPS REST认证头Authorization: Bearer {api_key}Content-Typeapplication/json超时settings.LLM_TIMEOUT默认 120s重定向follow_redirectsTrueHTTP 库httpx.AsyncClientAPI 端点构造{base_url}/chat/completionsPayload 结构OpenAI 兼容{ model: {model_ep}, messages: [ {role: system, content: ...}, {role: user, content: ...} ], temperature: 0.3, max_tokens: 1024 }B.DoubaoSeed2LiteEngine— 业务语义引擎包装了结构分析、缺口识别、SVT 生成三类业务语义的 LLM 调用。方法功能temperaturemax_tokens兜底行为analyze_sample_structure()爆款结构分析0.31024_get_fallback_structure()generate_material_gap_analysis()素材缺口识别0.2512_get_fallback_gap_analysis()generate_svt_json()SVT 时间线生成0.71024_get_fallback_svt_json()统一执行流程每个方法均遵循① 构建 messages (system user) ② 检查 api_key_provided() → 否则直接返回兜底模板 ③ await llm_client.chat_completion(...) ④ raw result[choices][0][message][content].strip() ⑤ self.last_raw_llm_output raw ← 原始文本存档供前端 Markdown 审计 ⑥ parsed fix_incomplete_json(raw) ← JSON 修复 ⑦ 归一化处理analyze / gaps 方法 ⑧ 返回处理结果 或 兜底模板关键属性last_raw_llm_output每次 LLM 调用后立即存入原始返回文本通过 API 响应传回前端用于 Markdown 代码块渲染可审计 LLM 输出。C. JSON 修复引擎 (fix_incomplete_json 4 策略修复器)设计目标LLM 返回的 JSON 常因截断、尾随逗号、未引用键名、Python 布尔值True/False/None等问题无法被json.loads()直解。4 策略累积式修复管道原始文本 ↓ strip() 去 Markdown 代码块包裹 (json ... ) ↓ json.loads() 直解 ──成功→ 返回 ↓ 失败 ↓ _repair_json_text() │ ├─ 策略1: _repair_trailing_commas() — ,} → } ,] → ] │ ├─ 策略2: _repair_unquoted_keys() — key: → key: True→true │ ├─ 策略3: _repair_nested_truncation() — 补全缺失的 } │ └─ 策略4: _repair_truncated_braces() — 按花括号栈截断到最后一个完整对象 │ 累积策略结果策略间不重置文本 ↓ json.loads() 验证 ──成功→ 返回 ↓ 失败 ↓ 返回 {}空 dict触发兜底模板关键片段— 花括号栈截断算法_repair_truncated_braces伪代码 遍历字符 text[i] if c { → brace_stack.push(i) if c } 且 brace_stack 非空 → brace_stack.pop() if brace_stack 变为空 → last_object_pos i 记录最后一个完整 JSON 对象结束位置 返回 text[:last_object_pos 1]D. 智能归一化引擎 (normalize_llm_output_to_structurenormalize_gap_analysis)设计目标解耦 LLM 自由输出格式与系统标准数据结构。LLM 的输出字段名可能因 prompt 调优、模型升级而变化——归一化引擎在此处充当适配器。结构归一化映射表normalize_llm_output_to_structureLLM 输出字段目标字段映射逻辑basic_video_attribute.total_duration_secscript_structure.{hook/body/cta}.duration按 20%-60%-20% 比例分配basic_video_attribute.content_form_attributetempo_structure.overall_rhythm直接赋值explosive_structure_evaluation.hook_part.rationality_commentscript_structure.hook.content直接赋值explosive_structure_evaluation.hook_part.actual_duration_secscript_structure.hook.duration覆盖默认 20% 分配explosive_structure_evaluation.main_content_part.*script_structure.body.segments[0].*直接映射explosive_structure_evaluation.cta_conversion_part.*script_structure.cta.*直接映射overall_structure_scoretempo_structure.overall_score直接赋值optimization_tippackaging_structure.optimization_suggestion直接赋值缺口归一化映射表normalize_gap_analysisLLM 输出字段目标字段缺口明细列表[].缺口分类identified_gaps[].slot_name缺口明细列表[].缺口优先级identified_gaps[].gap_type缺口明细列表[].缺口描述identified_gaps[].suggested_completion_strategy如果 LLM 直接返回identified_gaps字段已是标准格式归一化器会原样透传。E. 数据压缩工具 (compact_*)函数压缩对象压缩后大小目的compact_sample_data_for_llm()视频样例数据含关键帧 Base64仅保留 fps, duration, resolution 脚本预估避免 token 超限compact_structure_for_svt()结构模板完整三层结构仅保留 hook_dur, body_dur, cta_dur, rhythm, total_score压缩后注入 SVT promptcompact_gaps_for_svt()缺口分析完整 identified_gaps取前 5 条每条策略截取 60 字符压缩后注入 SVT prompt1.3.5backend/gap_completion.py— 缺口补全引擎属性值内部依赖持有独立的DoubaoSeed2LiteEngine实例设计模式策略模式策略分发逻辑_apply_completion_strategy策略关键词补全方法输出类型subtitle/文案_generate_subtitle_completion()字幕文案文本card/卡片_generate_sales_card()卖点卡片数据结构animation/动画_generate_animation_template()动画模板参数其他_generate_generic_completion()简单文本叠加多版本生成generate_multiple_versions遍历[high_click, high_conversion, high_rhythm, high_quality]每个版本独立调用llm.generate_svt_json()失败时降级为base_svt。1.3.6backend/main.py— FastAPI 路由层属性值框架FastAPI 0.109.0中间件CORSallow_origins[*]实例化全局单例VideoProcessor(),DoubaoSeed2LiteEngine(),GapCompletionEngine()REST 端点清单9 个方法路径参数来源Content-TypeGET/—application/jsonPOST/api/upload-sampleUploadFile(multipart)multipart/form-dataPOST/api/analyze-structureForm(urlencoded)application/x-www-form-urlencodedPOST/api/identify-gapsForm(urlencoded)application/x-www-form-urlencodedPOST/api/complete-gapsForm(urlencoded)application/x-www-form-urlencodedPOST/api/generate-svtForm(urlencoded)application/x-www-form-urlencodedPOST/api/generate-multiple-versionsForm(urlencoded)application/x-www-form-urlencodedPOST/api/adjust-manuallyForm(urlencoded)application/x-www-form-urlencodedGET/api/config-status—application/json为什么用application/x-www-form-urlencoded而非multipart/form-data除上传端点需要传输二进制文件外其余端点传输的均为纯文本 JSON 字符串structure_template_json、gap_analysis_json等使用 urlencoded 避免 FastAPI multipart 解析器对纯文本字段的不稳定处理。1.3.7frontend/index.html— 前端单页应用属性值架构原生 HTML5 SPA无框架CSS 框架TailwindCSSCDN图标库FontAwesome 4.7CDNMarkdown 渲染Marked.jsCDN通信fetch()API →http://localhost:8000/api/*主题色primary#6366f1, secondary#ec4899, accent#10b981, dark#1e1b4b核心全局状态变量类型初始值写入时机currentTaskIdstringnull视频上传成功currentSampleDataobjectnull视频上传成功currentStructureTemplateobjectnull结构分析返回currentGapAnalysisobjectnull缺口识别返回currentSvtobjectnull多版本生成返回currentRawLlmOutputstring结构分析返回currentRawGapOutputstring缺口识别返回1.4 全链路数据流完整时序图User Browser FastAPI Backend VolcEngine Ark Filesystem │ │ │ │ │ ① POST /api/upload-sample (multipart video) │ │ │────────────────────────▶│ │ │ │ │── save to uploads/ │ │ │ │── VideoProcessor. │ │ │ │ process_sample_video()│ │ │ ② 200 {task_id, │ │ │ │ sample_data} │ │ │ │◀────────────────────────│ │ │ │ │ │ │ │ ③ POST /api/analyze-structure │ │ │ (task_id, sample_data_json) │ │ │────────────────────────▶│ │ │ │ │── compact_sample_data_for_llm() │ │ │── POST /chat/completions ────────────────────▶│ │ │ │ Doubao-Seed-2.0- │ │ │ │ lite 推理 │ │ │◀── 200 {choices[...]} ────────────────────────│ │ │── fix_incomplete_json() │ │ │── normalize_llm_output_to_structure() │ │ ④ 200 {task_id, │ │ │ │ structure_template, │ │ │ │ raw_llm_output} │ │ │ │◀────────────────────────│ │ │ │ │ │ │ │ ⑤ POST /api/identify-gaps │ │ │ (task_id, target_topic, │ │ │ new_materials_text, │ │ │ structure_template_json) │ │ │────────────────────────▶│ │ │ │ │── POST /chat/completions ────────────────────▶│ │ │◀── 200 {choices[...]} ────────────────────────│ │ │── fix_incomplete_json() │ │ │── normalize_gap_analysis() │ │ ⑥ 200 {gap_analysis, │ │ │ │ raw_gap_output} │ │ │ │◀────────────────────────│ │ │ │ │ │ │ │ ⑦ POST /api/generate-svt │ │ │ (task_id, structure_template_json, │ │ │ gap_analysis_json, target_topic, │ │ │ version_type) │ │ │────────────────────────▶│ │ │ │ │── compact_structure_for_svt() │ │ │── compact_gaps_for_svt() │ │ │── POST /chat/completions ────────────────────▶│ │ │◀── 200 {choices[...]} ────────────────────────│ │ │── fix_incomplete_json() │ │ ⑧ 200 {svt_json} │ │ │ │◀────────────────────────│ │ │ │ │ │ │ │ ⑨ [前端] exportSvtJson() / previewVideo() │ │ │ Blob 下载 / 模态弹窗 │ │关键数据转换节点节点输入转换输出T1原始视频文件 (MP4)OpenCV 解析sample_data(含 Base64 关键帧)T2sample_datacompact_sample_data_for_llm()压缩后的视频摘要T3LLM 原始返回文本fix_incomplete_json()Python dictT4Python dict (LLM 自由字段)normalize_llm_output_to_structure()标准structure_templateT5structure_templatecompact_structure_for_svt()结构摘要5 字段T6gap_analysiscompact_gaps_for_svt()缺口摘要≤5 条T7结构摘要 缺口摘要 版本特征LLM SVT 编译SVT-JSONT8SVT-JSONJSON.stringify()Blob浏览器下载文件T9SVT-JSON前端 DOM 计算时间线可视化弹窗1.5 关键技术栈服务端Python 3.10技术版本用途许可证风险FastAPI0.109.0异步 Web 框架MITUvicorn0.27.0ASGI 服务器BSD-3OpenCV-Python4.8.1.78视频帧读取/分析Apache 2.0NumPy1.26.3数组运算与均匀采样BSD-3httpx0.26.0异步 HTTP 客户端BSD-3PyYAML6.0.1YAML 配置文件解析MITPydantic2.5.3数据验证与序列化MITpython-multipart0.0.6multipart 文件上传解析Apache 2.0前端浏览器端技术版本/来源用途原生 HTML5—页面结构与 DOM APITailwindCSSCDN (cdn.tailwindcss.com)原子化 CSSFontAwesome 4.7CDN (cdn.jsdelivr.net)图标字体Marked.jsCDN (cdn.jsdelivr.net)Markdown → HTML 渲染Fetch API浏览器原生HTTP 异步通信URLSearchParams浏览器原生urlencoded 表单编码Blob / URL.createObjectURL浏览器原生文件下载1.6 组件间交互关系依赖注入隐式单例模式项目中未使用正式的 DI 容器而是通过模块级全局变量实现单例# backend/main.py (L22-L24) video_processor VideoProcessor() llm_client DoubaoSeed2LiteEngine() gap_engine GapCompletionEngine()影响优点简单直接无额外依赖缺点模块加载顺序敏感测试时难以 mockGapCompletionEngine内部又持有独立的DoubaoSeed2LiteEngine实例模块间调用关系矩阵调用者 \ 被调用者configvideo_processorVolcEngineLLMClientDoubaoSeed2LiteGapCompletionmain.py(入口)—————backend/main.py✓✓—✓✓config.py—————video_processor.py—————llm_client.py✓—✓✓—gap_completion.py——✓✓—