2312

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+backend/cache/models--BAAI--bge-small-zh/blobs/5930ef2631f95185a3b74db3dcff787376bc93cdf693321ef75b2d4ed3b3545d filter=lfs diff=lfs merge=lfs -text
+backend/cache/models--BAAI--bge-small-zh/blobs/5cc750eb4f5412313aba1482e53aeccd1ed0b97bc213f2962e0c80e6c8809319 filter=lfs diff=lfs merge=lfs -text
+backend/temp_gorilla/berkeley-function-call-leaderboard/architecture_diagram.png filter=lfs diff=lfs merge=lfs -text

backend/.dockerignore

@@ -0,0 +1,53 @@
+# 1. Python 编译产物（无需打包进镜像）
+__pycache__/
+*.py[cod]
+*$py.class
+.mypy_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# 2. 虚拟环境（镜像内会重新安装依赖，本地虚拟环境无需打包）
+.venv/
+venv/
+ENV/
+env/
+
+# 3. 敏感/配置文件（避免密钥、本地配置打包进镜像）
+.env
+.env.local
+.env.*.local
+*.env
+secrets/
+
+# 4. 项目临时/大文件（减少镜像体积）
+temp_docs/  # 文档上传临时目录
+model_cache/  # 本地模型缓存（镜像内可按需下载或挂载）
+~/.cache/huggingface/  # 本地 HuggingFace 模型缓存
+~/.cache/torch/
+*.log
+*.tmp
+.DS_Store
+Thumbs.db
+
+# 5. 版本控制/构建产物（无需打包）
+.git/
+.gitignore
+.github/
+dist/
+build/
+*.egg-info/
+
+# 6. Docker 相关（避免循环打包）
+.dockerignore
+Dockerfile
+docker-compose.yml
+*.dockerfile
+src/*.py
+electron_app/
+
+# 7. 其他无关文件
+README.md
+LICENSE
+*.txt
+*.md

backend/Dockerfile.backend

@@ -0,0 +1,18 @@
+# Hugging Face 官方标准格式 —— 必须这样写
+FROM python:3.11-slim
+
+# 固定配置
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+WORKDIR /app
+
+# 安装依赖
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
+
+# 复制代码
+COPY --chown=user . /app
+
+# 必须端口 7860
+CMD ["uvicorn", "backend.backend_app.main:app", "--host", "0.0.0.0", "--port", "7860"]

backend/backend_app/api/api_router.py

@@ -0,0 +1,23 @@
+
+from fastapi import APIRouter
+
+from backend_app.api.llm_api.newUpdateFile.new_updateFile import new_updateFile_router
+from backend_app.api.llm_api.universal.universal_router import universal_router
+from backend_app.api.llm_api.ingest.ingest import ingest_router
+from backend_app.api.voice.voice_router import voice_router
+from backend_app.api.video.video_router import video_router
+
+api_router = APIRouter()
+
+api_router.include_router(new_updateFile_router, prefix="/new_update_file", tags=["new_update_file"])
+
+api_router.include_router(ingest_router, prefix="/ingest", tags=["ingest"])
+
+# universal enterprise assistant
+api_router.include_router(universal_router, prefix="/universal", tags=["universal"])
+
+# voice generation service
+api_router.include_router(voice_router, prefix="/voice", tags=["voice"])
+
+# video generation service
+api_router.include_router(video_router, prefix="/video", tags=["video"])

backend/backend_app/api/llm_api/ingest/ingest.py

@@ -0,0 +1,185 @@
+import json
+from typing import Dict
+from fastapi import APIRouter, Form, HTTPException
+
+from datetime import datetime
+import logging
+import os
+from pydantic import BaseModel
+from helloAgents.tools.registry import global_registry
+from helloAgents.tools.builtin.rag_tool import RAGTool
+# 2. 定义请求体
+class FileListRequest(BaseModel):
+    user_id: str
+
+logger = logging.getLogger(__name__)
+ingest_router = APIRouter()
+
+# ------------------------------
+# ⚙️ 企业级配置（和你原有一致）
+# ------------------------------
+MANIFEST_FILE = ".file_manifest.json"
+CHUNK_SIZE = 8192
+MAX_PARALLEL_FILES = 4
+SAVE_BASE_DIR = "./knowledge_base"  # 统一基座目录
+
+# ------------------------------
+# 🆕 新增：获取用户上传文档接口
+# ------------------------------
+@ingest_router.post("/list")
+async def get_user_uploaded_files(body: FileListRequest):
+    """
+    获取指定命名空间下所有已上传的文件列表
+    返回：所有真实文件、文件路径、哈希、去重状态、文件信息
+    """
+    user_id = body.user_id
+    if not user_id.strip():
+        raise HTTPException(status_code=400, detail="用户ID不能为空")
+
+    # 用户文件目录
+    user_dir = os.path.join(SAVE_BASE_DIR, user_id)
+    if not os.path.exists(user_dir):
+        return {
+            "success": True,
+            "user_id": user_id,
+            "total_files": 0,
+            "files": [],
+            "msg": "该用户暂无上传文件"
+        }
+
+    # 加载 manifest 清单（你原有去重/版本管理核心）
+    manifest = load_manifest(user_dir)
+    if not manifest:
+        return {
+            "success": True,
+            "user_id": user_id,
+            "total_files": 0,
+            "files": [],
+            "msg": "该用户暂无上传文件（清单为空）"
+        }
+
+    # 构建文件列表
+    file_list = []
+    for filename, file_hash in manifest.items():
+        file_path = os.path.join(user_dir, filename)
+        
+        # 获取文件基本信息
+        file_stat = os.stat(file_path)
+        create_time = datetime.fromtimestamp(file_stat.st_ctime).strftime("%Y-%m-%d %H:%M:%S")
+        update_time = datetime.fromtimestamp(file_stat.st_mtime).strftime("%Y-%m-%d %H:%M:%S")
+        file_size = file_stat.st_size  # 字节
+
+        # 文件格式
+        _, ext = os.path.splitext(filename)
+        ext = ext.lower().lstrip(".")
+
+        file_list.append({
+            "filename": filename,
+            "original_filename": filename.split("_v")[0] + "." + ext if "_v" in filename else filename,
+            "file_path": file_path,
+            "file_hash": file_hash,
+            "file_type": ext,
+            "file_size_bytes": file_size,
+            "file_size": f"{round(file_size / 1024 / 1024, 2)} MB" if file_size > 1024*1024 else f"{round(file_size / 1024, 2)} KB",
+            "create_time": create_time,
+            "update_time": update_time,
+            "is_versioned": "_v" in filename  # 是否是版本文件
+        })
+
+    # 按上传时间倒序排列（最新在前）
+    file_list = sorted(file_list, key=lambda x: x["create_time"], reverse=True)
+
+    return {
+        "success": True,
+        "user_id": user_id,
+        "total_files": len(file_list),
+        "files": file_list,
+        "msg": f"成功获取 {len(file_list)} 个文件"
+    }
+
+
+
+def load_manifest(ns_path: str) -> Dict[str, str]:
+    manifest_path = os.path.join(ns_path, MANIFEST_FILE)
+    if os.path.exists(manifest_path):
+        try:
+            with open(manifest_path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except Exception:
+            logger.warning(f"读取 manifest 失败: {manifest_path}")
+            return {}
+    return {}
+
+
+
+
+class DeleteFileListRequest(BaseModel):
+    user_id: str
+    doc_id: str
+# ------------------------------
+# 🗑️ 新增：删除文档接口（通过 file_hash 删除）
+# ------------------------------
+@ingest_router.post("/delete")
+async def delete_file_by_hash(
+    body: DeleteFileListRequest
+):
+    # 接收前端传来的 user_id 和 doc_id
+    user_id = body.user_id
+    doc_id = body.doc_id    
+    if not user_id.strip() or not doc_id.strip():
+        raise HTTPException(status_code=400, detail="user_id 和 doc_id 不能为空")
+
+    user_dir = os.path.join(SAVE_BASE_DIR, user_id)
+    manifest = load_manifest(user_dir)
+
+    # 1. 通过 doc_id 找到对应的文件名
+    target_filename = None
+    for filename, f_doc_id in manifest.items():
+        if f_doc_id == doc_id:
+            target_filename = filename
+            break
+
+    if not target_filename:
+        raise HTTPException(status_code=404, detail="文件不存在或已删除")
+
+    # 2. 删除真实文件
+    file_path = os.path.join(user_dir, target_filename)
+    if os.path.exists(file_path):
+        os.remove(file_path)
+
+    # 3. 从 manifest 中移除
+    del manifest[target_filename]
+    save_manifest(user_dir, manifest)
+
+    # 删除向量库
+    rag_tool: RAGTool = global_registry.get_tool("rag")
+    result = rag_tool.run({
+        "action": "delete_document",
+        "user_id": user_id,
+        "doc_id": doc_id
+    })
+
+    if result:
+        return {
+        "success": True,
+        "msg": "删除成功",
+        "filename": target_filename,
+        "doc_id": doc_id
+    }
+    else:
+        return {
+            "success": False,
+            "msg": "删除失败，请手动检查",
+            "filename": target_filename,
+            "doc_id": doc_id
+        }
+
+    
+
+
+def save_manifest(ns_path: str, manifest: Dict[str, str]):
+    manifest_path = os.path.join(ns_path, MANIFEST_FILE)
+    temp_path = manifest_path + ".tmp"
+    with open(temp_path, "w", encoding="utf-8") as f:
+        json.dump(manifest, f, indent=2, ensure_ascii=False)
+    os.replace(temp_path, manifest_path)

backend/backend_app/api/llm_api/newUpdateFile/new_updateFile.py

@@ -0,0 +1,245 @@
+from fastapi import APIRouter, Request, UploadFile, File, Form, HTTPException
+from typing import List, Dict
+from datetime import datetime
+import logging
+import os
+import asyncio
+import hashlib
+import json
+import tempfile
+import shutil
+
+from helloAgents.tools.async_executor import AsyncToolExecutor
+from helloAgents.tools.builtin.rag_tool import RAGTool
+from helloAgents.tools.builtin.memory_tool import MemoryTool
+from helloAgents.tools.registry import global_registry
+
+from redis_config import get_redis, QUEUE_RAG_QDRANT, QUEUE_RAG_NEO4J, QUEUE_MEMORY
+redis = get_redis()
+
+logger = logging.getLogger(__name__)
+new_updateFile_router = APIRouter()
+
+# ------------------------------
+# ⚙️ 企业级配置
+# ------------------------------
+MANIFEST_FILE = ".file_manifest.json"
+CHUNK_SIZE = 8192
+MAX_PARALLEL_FILES = 4
+
+# ------------------------------
+# 🛠️ 核心工具函数
+# ------------------------------
+
+def load_manifest(ns_path: str) -> Dict[str, str]:
+    manifest_path = os.path.join(ns_path, MANIFEST_FILE)
+    if os.path.exists(manifest_path):
+        try:
+            with open(manifest_path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except Exception:
+            logger.warning(f"读取 manifest 失败: {manifest_path}")
+            return {}
+    return {}
+
+def save_manifest(ns_path: str, manifest: Dict[str, str]):
+    manifest_path = os.path.join(ns_path, MANIFEST_FILE)
+    temp_path = manifest_path + ".tmp"
+    with open(temp_path, "w", encoding="utf-8") as f:
+        json.dump(manifest, f, indent=2, ensure_ascii=False)
+    os.replace(temp_path, manifest_path)
+
+def calculate_file_hash_stream(file_path: str) -> str:
+    sha256 = hashlib.sha256()
+    with open(file_path, "rb") as f:
+        while chunk := f.read(CHUNK_SIZE):
+            sha256.update(chunk)
+    return sha256.hexdigest()
+
+def calculate_upload_hash_stream(file_obj) -> str:
+    sha256 = hashlib.sha256()
+    file_obj.file.seek(0)
+    while chunk := file_obj.file.read(CHUNK_SIZE):
+        sha256.update(chunk)
+    file_obj.file.seek(0)
+    return sha256.hexdigest()
+
+async def save_file_with_version_and_deduplicate(
+    upload_file: UploadFile,
+    user_id: str,
+    save_dir: str = "./knowledge_base"
+) -> dict:
+    original_name = upload_file.filename.strip()
+    name, ext = os.path.splitext(original_name)
+    ns_path = os.path.join(save_dir, user_id)
+
+    os.makedirs(ns_path, exist_ok=True)
+    manifest = load_manifest(ns_path)
+
+    try:
+        new_file_hash = calculate_upload_hash_stream(upload_file)
+
+        for existing_name, existing_hash in manifest.items():
+            if existing_hash == new_file_hash:
+                return {
+                    "success": True,
+                    "is_duplicate": True,
+                    "filename": original_name,
+                    "file_path": os.path.join(ns_path, existing_name),
+                    "message": f"内容已存在（同名：{existing_name}），自动去重"
+                }
+
+        target_name = original_name
+        version = 1
+        while target_name in manifest:
+            version += 1
+            target_name = f"{name}_v{version}{ext}"
+        
+        final_path = os.path.join(ns_path, target_name)
+
+        with tempfile.NamedTemporaryFile(dir=ns_path, delete=False) as tmp_file:
+            shutil.copyfileobj(upload_file.file, tmp_file)
+            temp_file_path = tmp_file.name
+        
+        os.replace(temp_file_path, final_path)
+
+        manifest[target_name] = new_file_hash
+        save_manifest(ns_path, manifest)
+
+        return {
+            "success": True,
+            "is_duplicate": False,
+            "filename": original_name,
+            "file_path": final_path,
+            "hash": new_file_hash,
+            "message": f"已保存（版本 v{version})" if version > 1 else "已保存"
+        }
+
+    except Exception as e:
+        logger.error(f"保存失败 {upload_file.filename}: {str(e)}")
+        return {
+            "success": False,
+            "filename": upload_file.filename,
+            "error": str(e)
+        }
+
+# ------------------------------
+# 主处理逻辑（已补全记忆）
+# ------------------------------
+async def process_uploaded_files(files: List[UploadFile], user_id: str) -> dict:
+    memory_tool: MemoryTool = global_registry.get_tool("memory")
+    rag_tool: RAGTool = global_registry.get_tool("rag")
+
+    if not files:
+        raise HTTPException(status_code=400, detail="请上传至少一个文件")
+    if not user_id.strip():
+        raise HTTPException(status_code=400, detail="命名空间不能为空")
+
+    semaphore = asyncio.Semaphore(MAX_PARALLEL_FILES)
+    
+    async def save_with_limit(f):
+        async with semaphore:
+            return await save_file_with_version_and_deduplicate(f, user_id)
+
+    save_tasks = [save_with_limit(f) for f in files]
+    save_results = await asyncio.gather(*save_tasks)
+
+    saved_files = []
+    save_errors = []
+    duplicate_files = []
+
+    for res in save_results:
+        if not res["success"]:
+            save_errors.append(res)
+        elif res.get("is_duplicate"):
+            duplicate_files.append(res)
+        else:
+            saved_files.append(res)
+
+    # ============================
+    # ✅ 企业级精简版：只存 1 条总结记忆（包含所有文件路径+状态）
+    # ============================
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    total = len(files)
+    success_cnt = len(saved_files)
+    dup_cnt = len(duplicate_files)
+    fail_cnt = len(save_errors)
+
+    # 构建清晰的文件清单
+    success_files = "\n".join([f"- {f['filename']} | 路径：{f['file_path']}" for f in saved_files])
+    dup_files_list = "\n".join([f"- {d['filename']}" for d in duplicate_files])
+    err_files_list = "\n".join([f"- {e['filename']} | 原因：{e['error']}" for e in save_errors])
+
+    # ============================
+    # ✅ 记忆存储结束
+    # ============================
+    summary_content = f"""【文件上传总结】{now} | 用户：{user_id}
+        总文件数：{total}
+        ✅ 上传成功：{success_cnt} 个
+        {success_files if success_files else '无'}
+
+        ⚠️ 重复文件：{dup_cnt} 个
+        {dup_files_list if dup_files_list else '无'}
+
+        ❌ 上传失败：{fail_cnt} 个
+        {err_files_list if err_files_list else '无'}
+        """
+    summary_tasks = {
+        "action": "add",
+        "user_id": user_id,
+        "memory_type": "episodic",
+        "content": summary_content.strip(),
+        "importance": 0.8,
+        "session_id": None
+    }
+    redis.rpush(QUEUE_MEMORY, json.dumps(summary_tasks))
+
+    if not saved_files:
+        return {
+            "success": len(save_errors) == 0,
+            "msg": f"去重 {len(duplicate_files)} 个 | 失败 {len(save_errors)} 个",
+            "duplicate_count": len(duplicate_files),
+            "results": [],
+            "errors": save_errors,
+            "duplicates": duplicate_files
+        }
+
+    # RAG qdrant 入库
+    task = {
+        "action": "add_document",
+        "file_path": saved_files,
+        "user_id": user_id
+    }
+    redis.rpush(QUEUE_RAG_QDRANT, json.dumps(task))
+
+    # RAG neo4j 入库
+    task_neo4j = {
+        "action": "add_neo4j_document",
+        "file_path": saved_files,
+        "user_id": user_id
+    }
+    redis.rpush(QUEUE_RAG_NEO4J, json.dumps(task_neo4j))
+
+
+    return {
+        "success": True,
+        "msg": f"成功 {len(saved_files)} | 去重 {len(duplicate_files)}",
+        "data": {
+            "total": len(files),
+            "saved": len(saved_files),
+            "success": saved_files,
+            "duplicate_files": duplicate_files,
+            "namespace": user_id
+        }
+    }
+
+# ------------------------------
+# 路由
+# ------------------------------
+@new_updateFile_router.post("/new_update_file")
+async def new_update_file(
+    request: Request,
+    files: List[UploadFile] = File(..., description="支持 txt, md, pdf, docx, doc, json"),
+    namespace: str = Form(..., description="命名空间")
+) -> dict:
+    return await process_uploaded_files(files, namespace)

backend/backend_app/api/llm_api/universal/__init__.py

@@ -0,0 +1 @@
+"""全能企业级助手API模块"""

backend/backend_app/api/llm_api/universal/universal_router.py

@@ -0,0 +1,128 @@
+import re
+import asyncio
+import nest_asyncio
+from datetime import datetime
+from fastapi import APIRouter, Request, HTTPException
+from pydantic import BaseModel, Field, field_validator
+from typing import Optional, Dict, Any
+import logging
+
+from helloAgents.agents.universal_enterprise_agent import KnowledgeBaseAssistant
+from helloAgents.core.llm import HelloAgentsLLM
+from helloAgents.tools.registry import global_registry
+from helloAgents.core.exceptions import (
+    HelloAgentsException,
+    ToolException
+)
+nest_asyncio.apply()
+
+# 评估工具
+from helloAgents.tools.builtin.bfcl_evaluation_tool import BFCLEvaluationTool
+
+logger = logging.getLogger(__name__)
+universal_router = APIRouter()
+
+# ==================== 请求/响应模型 ====================
+class UniversalChatRequest(BaseModel):
+    text: str = Field(..., description="用户输入的文本", max_length=5000)
+    user_id: str = Field(..., description="用户ID（必需）")
+    agent_id: Optional[str] = Field("universal_assistant")
+    session_id: Optional[str] = Field(None)
+    enable_memory: Optional[bool] = Field(True)
+    enable_rag: Optional[bool] = Field(True)
+    max_context_length: Optional[int] = Field(2000, ge=100, le=8000)
+    tool_choice: Optional[str] = Field("auto")
+
+    @field_validator("user_id")
+    def validate_user_id(cls, v):
+        if not re.match(r"^[a-zA-Z0-9_-]{3,50}$", v):
+            raise ValueError("用户ID格式错误")
+        return v
+
+class UniversalChatResponse(BaseModel):
+    success: bool
+    data: str
+    session_id: str
+    user_id: str
+    agent_id: str
+    tool_calls: Optional[int]
+    timestamp: str
+
+class ToolStatisticsResponse(BaseModel):
+    success: bool
+    statistics: Dict[str, Any]
+    timestamp: str
+
+# ==================== 【终极正确】异步Agent → 同步适配（FastAPI安全版）====================
+class SyncAgentWrapper:
+    def __init__(self, async_agent):
+        self.agent = async_agent
+        self.name = async_agent.name
+
+    def run(self, prompt, **kwargs):
+        # ✅ 唯一在 FastAPI 中安全运行异步 Agent 的方式
+        return asyncio.run(self.agent.run(prompt,** kwargs))
+
+# ==================== 正常聊天接口 ====================
+@universal_router.post("/chat", response_model=UniversalChatResponse)
+async def universal_chat(
+    request: Request,
+    body: UniversalChatRequest
+) -> UniversalChatResponse:
+    try:
+        agent = KnowledgeBaseAssistant(
+            name="通用助手",
+            llm=HelloAgentsLLM(),
+            tool_registry=global_registry
+        )
+
+        response = await agent.run(
+            input_text=body.text,
+            user_id=body.user_id,
+            agent_id=body.agent_id,
+            session_id=body.session_id
+        )
+
+        session_id = body.session_id or f"ses_{int(datetime.now().timestamp())}"
+
+        return UniversalChatResponse(
+            success=True,
+            data=response,
+            session_id=session_id,
+            user_id=body.user_id,
+            agent_id=body.agent_id,
+            tool_calls=0,
+            timestamp=datetime.now().isoformat()
+        )
+
+    except HelloAgentsException as e:
+        logger.error(f"业务异常: {e}", exc_info=True)
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"聊天失败: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail="服务内部错误")
+
+# ==================== 【独立】BFCL评估接口（不影响正常业务） ====================
+@universal_router.get("/bfcl-eval")
+def run_bfcl_evaluation():  # 注意：这里必须是 同步函数！
+    try:
+        # 初始化
+        llm = HelloAgentsLLM()
+        agent = KnowledgeBaseAssistant(name="BFCL-Eval-Agent", llm=llm)
+        sync_agent = SyncAgentWrapper(agent)
+
+        # 执行评估
+        bfcl_tool = BFCLEvaluationTool()
+        result = bfcl_tool.run(
+            agent=sync_agent,
+            category="simple_python",
+            max_samples=0,
+            run_official_eval=True
+        )
+
+        return {
+            "success": True,
+            "result": result
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}

backend/backend_app/api/video/README.md

@@ -0,0 +1,428 @@
+# 视频生成API文档
+
+## 概述
+视频生成API提供企业级文本到视频生成服务，支持多种视频风格、分辨率、时长等参数控制，可生成MP4、AVI、MOV等多种格式的视频文件，支持背景音乐和语音解说。
+
+## API端点
+
+### 1. 生成视频
+**POST** `/api/v1/video/generate`
+
+**请求体：**
+```json
+{
+  "prompt": "一只小鸟从天空飞过，落在树枝上，背景是森林",
+  "style": "animation",
+  "duration": 5,
+  "resolution": "720p",
+  "aspect_ratio": "16:9",
+  "frame_rate": 30,
+  "background_music": false,
+  "voice_over": true,
+  "voice_over_text": "这是一只美丽的小鸟，它在森林中自由飞翔",
+  "user_id": "user_12345"
+}
+```
+
+**参数说明：**
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| prompt | string | 是 | - | 视频描述文本，最长2000字符 |
+| style | string | 否 | animation | 视频风格：animation(动画)、realistic(真人实拍)、3d(3D建模)、cartoon(卡通)、cinematic(电影感) |
+| duration | int | 否 | 5 | 视频时长（秒），范围1-60 |
+| resolution | string | 否 | 720p | 分辨率：480p、720p、1080p、4k |
+| aspect_ratio | string | 否 | 16:9 | 宽高比：16:9、4:3、1:1、9:16 |
+| frame_rate | int | 否 | 30 | 帧率，范围1-60 |
+| background_music | bool | 否 | false | 是否添加背景音乐 |
+| voice_over | bool | 否 | false | 是否添加语音解说 |
+| voice_over_text | string | 否 | null | 语音解说文本 |
+| user_id | string | 否 | null | 用户ID，用于统计和配额管理 |
+
+**响应：**
+```json
+{
+  "success": true,
+  "video_url": "/api/video/files/video_abc123.mp4",
+  "video_id": "video_abc123",
+  "duration": 5,
+  "file_size": 1024000,
+  "resolution": "720p",
+  "format": "mp4",
+  "thumbnail_url": "/api/video/files/thumbnails/thumb_abc123.jpg",
+  "timestamp": "2024-01-01T12:00:00",
+  "estimated_generation_time": 30
+}
+```
+
+### 2. 获取视频状态
+**POST** `/api/v1/video/status`
+
+**请求体：**
+```json
+{
+  "video_id": "video_abc123"
+}
+```
+
+**响应：**
+```json
+{
+  "success": true,
+  "video_id": "video_abc123",
+  "status": "processing",
+  "progress": 65.5,
+  "estimated_completion_time": "2024-01-01T12:01:30",
+  "message": "正在生成视频帧...",
+  "timestamp": "2024-01-01T12:00:30"
+}
+```
+
+**状态说明：**
+- `pending`: 等待处理
+- `processing`: 处理中
+- `completed`: 已完成
+- `failed`: 失败
+
+### 3. 获取视频文件
+**GET** `/api/v1/video/files/{video_id}.{format}`
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| video_id | string | 是 | 视频文件ID |
+| format | string | 是 | 文件格式：mp4、avi、mov、webm |
+
+**响应：**
+返回视频文件流，Content-Type为对应的视频类型。
+
+### 4. 获取视频缩略图
+**GET** `/api/v1/video/files/thumbnails/{thumbnail_filename}`
+
+**参数：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| thumbnail_filename | string | 是 | 缩略图文件名，格式：thumb_{video_id}.jpg |
+
+**响应：**
+返回缩略图文件流，Content-Type为image/jpeg。
+
+### 5. 获取支持的视频风格
+**GET** `/api/v1/video/supported-styles`
+
+**响应：**
+```json
+{
+  "success": true,
+  "styles": {
+    "animation": {"name": "动画", "description": "2D/3D动画风格"},
+    "realistic": {"name": "真人实拍", "description": "实拍视频效果"},
+    "3d": {"name": "3D建模", "description": "三维建模渲染"},
+    "cartoon": {"name": "卡通", "description": "卡通漫画风格"},
+    "cinematic": {"name": "电影感", "description": "电影级视觉效果"}
+  },
+  "resolutions": ["480p", "720p", "1080p", "4k"],
+  "formats": ["mp4", "avi", "mov", "webm"],
+  "timestamp": "2024-01-01T12:00:00"
+}
+```
+
+### 6. 列出视频文件
+**GET** `/api/v1/video/list?page=1&page_size=20`
+
+**查询参数：**
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| page | int | 否 | 1 | 页码 |
+| page_size | int | 否 | 20 | 每页数量 |
+
+**响应：**
+```json
+{
+  "success": true,
+  "videos": [
+    {
+      "video_id": "video_abc123",
+      "filename": "video_abc123.mp4",
+      "size": 1024000,
+      "created_at": "2024-01-01T12:00:00",
+      "format": "mp4",
+      "has_thumbnail": true
+    }
+  ],
+  "total": 8,
+  "page": 1,
+  "page_size": 20,
+  "timestamp": "2024-01-01T12:00:00"
+}
+```
+
+### 7. 删除视频文件
+**POST** `/api/v1/video/delete`
+
+**请求体：**
+```json
+{
+  "video_id": "video_abc123",
+  "confirm": true
+}
+```
+
+**响应：**
+```json
+{
+  "success": true,
+  "message": "视频文件已成功删除",
+  "timestamp": "2024-01-01T12:00:00"
+}
+```
+
+### 8. 健康检查
+**GET** `/api/v1/video/health`
+
+**响应：**
+```json
+{
+  "status": "healthy",
+  "service": "video_generation",
+  "output_dir": "./video_outputs",
+  "video_files_count": 15,
+  "thumbnail_files_count": 15,
+  "timestamp": "2024-01-01T12:00:00"
+}
+```
+
+## 错误处理
+
+所有API端点都遵循统一的错误响应格式：
+
+```json
+{
+  "detail": "错误描述信息"
+}
+```
+
+**HTTP状态码：**
+- 200: 请求成功
+- 400: 参数错误
+- 404: 资源不存在
+- 500: 服务器内部错误
+
+## 企业级功能
+
+### 1. 异步处理
+支持长视频生成的异步处理，可通过状态查询接口实时获取生成进度。
+
+### 2. 多格式支持
+支持多种视频格式和分辨率，满足不同场景需求。
+
+### 3. 缩略图生成
+自动为每个视频生成缩略图，便于预览和展示。
+
+### 4. 语音解说集成
+支持为视频添加语音解说，实现文本到语音再到视频的完整流程。
+
+### 5. 进度跟踪
+实时进度跟踪和状态更新，提供良好的用户体验。
+
+## 部署配置
+
+### 环境变量
+```
+# 视频引擎配置
+VIDEO_ENGINE=simulated  # simulated, moviepy, svd, runwayml
+VIDEO_API_KEY=your_api_key
+VIDEO_MODEL=svd
+
+# 存储配置
+STORAGE_TYPE=local  # local, s3, azure_blob, gcs
+STORAGE_BUCKET=video-bucket
+STORAGE_REGION=us-west-1
+
+# 异步处理配置
+VIDEO_ASYNC_PROCESSING=true
+MAX_WORKERS=4
+QUEUE_TIMEOUT=300
+
+# API配置
+API_RATE_LIMIT=30  # 视频生成较耗资源，限制更低
+API_AUTH_REQUIRED=false
+```
+
+### 依赖安装
+```bash
+# 基本依赖
+pip install fastapi uvicorn python-multipart
+
+# 视频处理依赖（根据选择的引擎）
+pip install moviepy          # 视频编辑和处理
+pip install opencv-python    # 计算机视觉库
+pip install pillow           # 图像处理
+
+# AI模型相关（用于高级视频生成）
+pip install diffusers        # 扩散模型（用于视频生成）
+pip install transformers     # 已包含
+pip install torch            # 已包含
+```
+
+## 使用示例
+
+### Python客户端
+```python
+import requests
+import time
+
+BASE_URL = "http://localhost:8000/api/v1"
+
+def generate_video(prompt, style="animation"):
+    # 提交生成请求
+    response = requests.post(f"{BASE_URL}/video/generate", json={
+        "prompt": prompt,
+        "style": style,
+        "duration": 5,
+        "resolution": "720p"
+    })
+
+    if response.status_code != 200:
+        print(f"提交失败: {response.text}")
+        return None
+
+    data = response.json()
+    if not data["success"]:
+        print(f"生成失败: {data.get('message')}")
+        return None
+
+    video_id = data["video_id"]
+    print(f"视频生成已提交，ID: {video_id}")
+
+    # 轮询状态
+    while True:
+        status_response = requests.post(f"{BASE_URL}/video/status", json={
+            "video_id": video_id
+        })
+
+        if status_response.status_code == 200:
+            status_data = status_response.json()
+            if status_data["success"]:
+                status = status_data["status"]
+                progress = status_data["progress"]
+
+                print(f"进度: {progress}% - 状态: {status}")
+
+                if status == "completed":
+                    print(f"视频生成完成: {data['video_url']}")
+                    return data
+                elif status == "failed":
+                    print("视频生成失败")
+                    return None
+
+        time.sleep(2)
+```
+
+### JavaScript/TypeScript客户端
+```typescript
+const API_BASE_URL = 'http://localhost:8000/api/v1';
+
+class VideoGenerator {
+  async generateVideo(prompt: string): Promise<any> {
+    // 提交生成请求
+    const response = await fetch(`${API_BASE_URL}/video/generate`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        prompt,
+        style: 'animation',
+        duration: 5,
+        resolution: '720p'
+      })
+    });
+
+    if (!response.ok) {
+      throw new Error(`提交失败: ${response.status}`);
+    }
+
+    const data = await response.json();
+    if (!data.success) {
+      throw new Error(`生成失败: ${data.message}`);
+    }
+
+    return data;
+  }
+
+  async checkStatus(videoId: string): Promise<any> {
+    const response = await fetch(`${API_BASE_URL}/video/status`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ video_id: videoId })
+    });
+
+    if (!response.ok) {
+      throw new Error(`状态查询失败: ${response.status}`);
+    }
+
+    return await response.json();
+  }
+
+  async downloadVideo(videoId: string, format: string = 'mp4'): Promise<void> {
+    const url = `${API_BASE_URL}/video/files/${videoId}.${format}`;
+    window.open(url, '_blank');
+  }
+}
+```
+
+## 性能优化建议
+
+1. **异步队列**：使用消息队列处理视频生成任务，避免阻塞主线程
+2. **GPU加速**：视频生成任务尽量使用GPU加速
+3. **分级存储**：热数据使用SSD，冷数据迁移到低成本存储
+4. **CDN分发**：生成的视频文件通过CDN分发，提高访问速度
+5. **预览优化**：先生成低分辨率预览，再生成全分辨率版本
+
+## 安全注意事���
+
+1. **内容审核**：对用户输入的描述文本进行内容安全审核
+2. **资源限制**：实施严格的资源使用限制，防止滥用
+3. **访问控制**：敏感操作需要身份验证和授权
+4. **数据隔离**：不同用户的数据进行逻辑或物理隔离
+5. **监控告警**：实时监控系统资源使用情况，设置告警阈值
+
+## 扩展功能
+
+### 1. 批量生成
+支持批量视频生成，提高处理效率。
+
+### 2. 自定义模板
+支持用户上传自定义视频模板。
+
+### 3. 高级编辑
+支持对生成的视频进行进一步编辑（裁剪、滤镜、字幕等）。
+
+### 4. 多语言支持
+支持更多语言的语音解说。
+
+### 5. 实时预览
+支持生成过程中的实时预览功能。
+
+## 故障排除
+
+### 常见问题
+1. **生成速度慢**：检查GPU资源是否充足，考虑升级硬件或优化算法
+2. **内存不足**：调整视频分辨率或时长，减少内存占用
+3. **文件太大**：调整视频编码参数，优化文件大小
+4. **质量不佳**：优化描述文本，调整生成参数
+5. **服务不可用**：检查依赖服务状态，查看错误日志
+
+### 日志查看
+```bash
+# 查看应用日志
+tail -f logs/application.log
+
+# 查看错误日志
+tail -f logs/error.log
+
+# 查看访问日志
+tail -f logs/access.log
+```