1

.idea/.gitignore

@@ -0,0 +1,5 @@
+# 默认忽略的文件
+/shelf/
+/workspace.xml
+# 基于编辑器的 HTTP 客户端请求
+/httpRequests/

.idea/PicExam.iml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.tmp" />
+      <excludeFolder url="file://$MODULE_DIR$/temp" />
+      <excludeFolder url="file://$MODULE_DIR$/tmp" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/PicExam.iml" filepath="$PROJECT_DIR$/.idea/PicExam.iml" />
+    </modules>
+  </component>
+</project>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

Dockerfile

@@ -1,16 +1,40 @@
 # Read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
-# you will also find guides on how best to write your Dockerfile
+# Dockerfile for Qwen-VL PicExam API with CPU inference optimization
 
-FROM python:3.9
+FROM python:3.10-slim
 
+# 安装系统依赖
+RUN apt-get update && apt-get install -y \
+    git \
+    wget \
+    curl \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# 创建用户
 RUN useradd -m -u 1000 user
 USER user
 ENV PATH="/home/user/.local/bin:$PATH"
 
+# 设置工作目录
 WORKDIR /app
 
+# 设置环境变量优化内存使用
+ENV PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512
+ENV TOKENIZERS_PARALLELISM=false
+ENV OMP_NUM_THREADS=4
+ENV MKL_NUM_THREADS=4
+
+# 复制并安装 Python 依赖
 COPY --chown=user ./requirements.txt requirements.txt
-RUN pip install --no-cache-dir --upgrade -r requirements.txt
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir --upgrade -r requirements.txt
 
+# 复制应用代码
 COPY --chown=user . /app
-CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+
+# 暴露端口
+EXPOSE 7860
+
+# 启动命令，增加内存和超时配置
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860", "--timeout-keep-alive", "300", "--workers", "1"]

README.md

@@ -6,7 +6,255 @@ colorTo: red
 sdk: docker
 pinned: false
 license: apache-2.0
-short_description: PicExam
+short_description: 基于 Qwen-VL 的图像理解 API，支持 16GB 内存 + CPU 推理
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🏆 PicExam - Qwen-VL 图像理解 API
+
+基于 Qwen2-VL-2B-Instruct 模型的图像理解 API，专门优化用于 16GB 内存 + 纯 CPU 推理环境。
+
+## ✨ 特性
+
+- 🧠 **智能图像理解**: 基于阿里巴巴 Qwen2-VL-2B-Instruct 模型
+- 💻 **CPU 优化**: 专门针对 CPU 推理进行优化，无需 GPU
+- 🔧 **内存友好**: 适配 16GB 内存环境，包含内存监控和优化
+- 🚀 **易于部署**: 支持本地运行和 Hugging Face Spaces 部署
+- 📝 **多种接口**: 支持文件上传和 base64 图片输入
+- 📊 **实时监控**: 内置内存使用监控和缓存管理
+
+## 🛠️ 系统要求
+
+- **内存**: 16GB RAM（推荐）
+- **处理器**: 多核 CPU（推荐 4 核以上）
+- **存储**: 至少 10GB 可用空间（用于模型下载）
+- **Python**: 3.10+
+
+## 🚀 快速开始
+
+### 本地运行
+
+1. **克隆项目**
+```bash
+git clone <repository-url>
+cd PicExam
+```
+
+2. **安装依赖**
+```bash
+pip install -r requirements.txt
+```
+
+3. **启动服务**
+```bash
+python start_local.py
+```
+
+或者直接使用 uvicorn：
+```bash
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+4. **访问 API**
+- API 服务: http://localhost:7860
+- 交互式文档: http://localhost:7860/docs
+
+### Docker 部署
+
+```bash
+docker build -t picexam .
+docker run -p 7860:7860 picexam
+```
+
+### Hugging Face Spaces 部署
+
+1. 将代码推送到 Hugging Face Spaces 仓库
+2. 确保 `README.md` 中的 YAML 配置正确
+3. Spaces 会自动构建和部署
+
+## 📖 API 使用说明
+
+### 🌐 浏览器访问
+
+- **主页面**: http://localhost:7860/ - 显示完整的 API 端点定义和使用方法
+- **Web 界面**: http://localhost:7860/web - 图形化操作界面，支持拖拽上传
+- **API 文档**: http://localhost:7860/docs - 交互式 API 文档 (Swagger UI)
+
+### 📡 API 端点
+
+#### 1. API 信息获取
+```bash
+curl http://localhost:7860/
+```
+返回完整的 API 端点定义、使用方法和示例
+
+#### 2. 健康检查
+```bash
+curl http://localhost:7860/health
+```
+
+#### 3. 图片分析（文件上传）
+```bash
+curl -X POST "http://localhost:7860/analyze_image" \
+  -F "image=@your_image.jpg" \
+  -F "question=请描述这张图片的内容"
+```
+
+#### 4. 图片分析（Base64 表单）
+```bash
+curl -X POST "http://localhost:7860/analyze_image_base64" \
+  -F "image_base64=data:image/jpeg;base64,/9j/4AAQ..." \
+  -F "question=这张图片中有什么？"
+```
+
+#### 5. 图片分析（JSON API）⭐ 推荐
+```bash
+curl -X POST "http://localhost:7860/analyze" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "image": "data:image/jpeg;base64,/9j/4AAQ...",
+    "prompt": "请详细描述这张图片的内容"
+  }'
+```
+
+**JSON API 响应格式:**
+```json
+{
+  "success": true,
+  "prompt": "请详细描述这张图片的内容",
+  "response": "这张图片显示了...",
+  "processing_time": 8.45,
+  "image_info": {
+    "size": "1024x768",
+    "mode": "RGB",
+    "format": "JPEG"
+  }
+}
+```
+
+#### 6. 内存状态监控
+```bash
+curl http://localhost:7860/memory_status
+```
+
+#### 7. 清理缓存
+```bash
+curl -X POST http://localhost:7860/clear_cache
+```
+
+### 🐍 Python 调用示例
+
+```python
+import requests
+import base64
+
+# 1. JSON API 调用（推荐）
+def analyze_image_json(image_base64, prompt):
+    response = requests.post('http://localhost:7860/analyze',
+        json={
+            "image": image_base64,
+            "prompt": prompt
+        })
+    return response.json()
+
+# 2. 文件上传调用
+def analyze_image_file(image_path, question):
+    with open(image_path, 'rb') as f:
+        response = requests.post('http://localhost:7860/analyze_image',
+            files={"image": f},
+            data={"question": question})
+    return response.json()
+
+# 使用示例
+result = analyze_image_json("data:image/jpeg;base64,/9j/4AAQ...", "描述这张图片")
+print(result['response'])
+```
+
+## 🧪 测试
+
+### 快速测试
+```bash
+python quick_test.py
+```
+
+### 完整功能测试
+```bash
+python test_api.py
+```
+
+### 使用示例演示
+```bash
+python example_usage.py
+```
+
+测试包括：
+- ✅ API 信息获取
+- ✅ 健康检查
+- ✅ 内存状态监控
+- ✅ 图片分析（文件上传）
+- ✅ 图片分析（Base64 表单）
+- ✅ 图片分析（JSON API）
+- ✅ 缓存清理
+
+## ⚙️ 配置优化
+
+### 内存优化设置
+
+项目已包含以下内存优化配置：
+
+- `torch_dtype=torch.float16`: 使用半精度浮点数
+- `low_cpu_mem_usage=True`: 启用低内存使用模式
+- `use_cache=False`: 禁用 KV 缓存
+- 环境变量优化: `PYTORCH_CUDA_ALLOC_CONF`, `TOKENIZERS_PARALLELISM`
+
+### 性能调优
+
+- `OMP_NUM_THREADS=4`: 限制 OpenMP 线程数
+- `MKL_NUM_THREADS=4`: 限制 MKL 线程数
+- 单 worker 模式避免内存重复
+
+## 📊 性能指标
+
+在 16GB 内存环境下的典型性能：
+
+- **模型加载时间**: 30-60 秒（首次）
+- **推理时间**: 5-15 秒/图片（取决于 CPU）
+- **内存使用**: 8-12GB（包含模型和系统）
+- **支持图片格式**: JPEG, PNG, WebP 等
+
+## 🔧 故障排除
+
+### 常见问题
+
+1. **内存不足**
+   - 关闭其他程序释放内存
+   - 使用 `/clear_cache` 接口清理缓存
+
+2. **模型下载慢**
+   - 配置 Hugging Face 镜像源
+   - 使用代理或 VPN
+
+3. **推理速度慢**
+   - 确保 CPU 有足够核心数
+   - 检查系统负载
+
+### 日志查看
+
+应用使用标准 Python logging，可通过以下方式查看详细日志：
+
+```bash
+export PYTHONPATH=.
+python -c "import logging; logging.basicConfig(level=logging.DEBUG)"
+uvicorn app:app --log-level debug
+```
+
+## 📄 许可证
+
+Apache License 2.0
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📞 支持
+
+如有问题，请在 GitHub Issues 中提出。

app.py

@@ -1,7 +1,537 @@
-from fastapi import FastAPI
+import os
+import torch
+import psutil
+import gc
+import time
+import json
+from fastapi import FastAPI, File, UploadFile, Form, Request
+from fastapi.responses import JSONResponse, FileResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+from transformers import Qwen2VLForConditionalGeneration, AutoTokenizer, AutoProcessor
+from qwen_vl_utils import process_vision_info
+from PIL import Image
+import io
+import base64
+import logging
 
-app = FastAPI()
+# 配置日志
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# 数据模型
+class AnalyzeRequest(BaseModel):
+    image: str  # base64 编码的图片
+    prompt: str = "请描述这张图片的内容"  # 提示词/问题
+
+class AnalyzeResponse(BaseModel):
+    success: bool
+    prompt: str
+    response: str
+    processing_time: float
+    image_info: dict = None
+    error: str = None
+
+app = FastAPI(title="Qwen-VL PicExam API", description="基于 Qwen2-VL-2B-Instruct 的图像理解 API")
+
+# 挂载静态文件
+app.mount("/static", StaticFiles(directory="static"), name="static")
+
+# 全局变量存储模型和处理器
+model = None
+processor = None
+tokenizer = None
+
+def load_model():
+    """加载 Qwen2-VL-2B-Instruct 模型（CPU 版本，适合 16GB 内存）"""
+    global model, processor, tokenizer
+
+    try:
+        logger.info("开始加载 Qwen2-VL-2B-Instruct 模型...")
+
+        model_name = "Qwen/Qwen2-VL-2B-Instruct"
+
+        # 设置环境变量优化内存使用
+        os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "max_split_size_mb:512"
+        os.environ["TOKENIZERS_PARALLELISM"] = "false"  # 避免分词器并行导致的内存问题
+
+        # 加载处理器和分词器
+        processor = AutoProcessor.from_pretrained(
+            model_name,
+            trust_remote_code=True
+        )
+        tokenizer = AutoTokenizer.from_pretrained(
+            model_name,
+            trust_remote_code=True
+        )
+
+        # 加载模型到 CPU，使用内存优化配置
+        model = Qwen2VLForConditionalGeneration.from_pretrained(
+            model_name,
+            torch_dtype=torch.float16,      # 使用 float16 减少内存使用
+            device_map="cpu",               # 强制使用 CPU
+            low_cpu_mem_usage=True,         # 低内存使用模式
+            trust_remote_code=True,
+            # 额外的内存优化选项
+            use_cache=False,                # 禁用 KV 缓存以节省内存
+            attn_implementation="eager",    # 使用 eager attention 实现
+        )
+
+        # 设置为评估模式
+        model.eval()
+
+        # 清理不必要的内存
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+        logger.info("模型加载成功！")
+        logger.info(f"模型参数数量: {sum(p.numel() for p in model.parameters()) / 1e6:.1f}M")
+
+        return True
+
+    except Exception as e:
+        logger.error(f"模型加载失败: {str(e)}")
+        return False
+
+# 启动时加载模型
+@app.on_event("startup")
+async def startup_event():
+    """应用启动时加载模型"""
+    success = load_model()
+    if not success:
+        logger.error("模型加载失败，应用可能无法正常工作")
 
 @app.get("/")
-def greet_json():
-    return {"Hello": "World!"}
+def api_documentation():
+    """API 文档和端点说明"""
+    return {
+        "service": "Qwen-VL PicExam API",
+        "description": "基于 Qwen2-VL-2B-Instruct 的图像理解 API，支持 16GB 内存 + CPU 推理",
+        "version": "1.0.0",
+        "model": "Qwen2-VL-2B-Instruct",
+        "status": {
+            "service": "running",
+            "model_loaded": model is not None,
+            "inference_mode": "CPU"
+        },
+        "endpoints": {
+            "GET /": {
+                "description": "获取 API 文档和端点信息",
+                "response": "JSON 格式的 API 说明"
+            },
+            "GET /health": {
+                "description": "健康检查接口",
+                "response": "服务状态信息"
+            },
+            "GET /web": {
+                "description": "Web 界面",
+                "response": "HTML 页面，提供图形化操作界面"
+            },
+            "POST /analyze_image": {
+                "description": "分析上传的图片文件",
+                "parameters": {
+                    "image": "图片文件 (multipart/form-data)",
+                    "question": "关于图片的问题 (可选，默认为描述图片内容)"
+                },
+                "example": "curl -X POST '/analyze_image' -F 'image=@photo.jpg' -F 'question=这张图片中有什么？'"
+            },
+            "POST /analyze_image_base64": {
+                "description": "分析 base64 编码的图片",
+                "parameters": {
+                    "image_base64": "base64 编码的图片数据",
+                    "question": "关于图片的问题 (可���)"
+                },
+                "example": "curl -X POST '/analyze_image_base64' -F 'image_base64=data:image/jpeg;base64,/9j/4AAQ...' -F 'question=描述这张图片'"
+            },
+            "POST /analyze": {
+                "description": "简化的图片分析接口 (JSON 格式)",
+                "parameters": {
+                    "image": "base64 编码的图片数据",
+                    "prompt": "提示词/问题"
+                },
+                "example": "curl -X POST '/analyze' -H 'Content-Type: application/json' -d '{\"image\":\"data:image/jpeg;base64,...\",\"prompt\":\"描述图片\"}'"
+            },
+            "GET /memory_status": {
+                "description": "获取内存使用状态",
+                "response": "系统内存和模型内存使用情况"
+            },
+            "POST /clear_cache": {
+                "description": "清理内存缓存",
+                "response": "缓存清理结果"
+            }
+        },
+        "usage_examples": {
+            "curl_file_upload": "curl -X POST 'http://localhost:7860/analyze_image' -F 'image=@your_image.jpg' -F 'question=请描述这张图片'",
+            "curl_base64": "curl -X POST 'http://localhost:7860/analyze_image_base64' -F 'image_base64=data:image/jpeg;base64,/9j/4AAQ...' -F 'question=这张图片中有什么？'",
+            "curl_json": "curl -X POST 'http://localhost:7860/analyze' -H 'Content-Type: application/json' -d '{\"image\":\"data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAA...\",\"prompt\":\"请详细描述这张图片的内容\"}'"
+        },
+        "supported_formats": ["JPEG", "PNG", "WebP", "BMP", "GIF"],
+        "memory_requirements": "16GB RAM recommended for optimal performance",
+        "inference_time": "5-15 seconds per image (depends on CPU)",
+        "documentation": "Visit /docs for interactive API documentation"
+    }
+
+@app.get("/health")
+def health_check():
+    """简单的健康检查接口"""
+    return {
+        "status": "healthy",
+        "service": "Qwen-VL PicExam API",
+        "model_loaded": model is not None,
+        "timestamp": time.time()
+    }
+
+@app.post("/analyze_image")
+async def analyze_image(
+    image: UploadFile = File(...),
+    question: str = Form("请描述这张图片的内容")
+):
+    """
+    分析上传的图片并回答问题
+
+    Args:
+        image: 上传的图片文件
+        question: 关于图片的问题（默认为描述图片内容）
+
+    Returns:
+        JSON 响应包含分析结果
+    """
+    if model is None or processor is None:
+        return JSONResponse(
+            status_code=503,
+            content={"error": "模型未加载，请稍后重试"}
+        )
+
+    try:
+        # 读取图片
+        image_bytes = await image.read()
+        pil_image = Image.open(io.BytesIO(image_bytes))
+
+        # 确保图片是 RGB 格式
+        if pil_image.mode != 'RGB':
+            pil_image = pil_image.convert('RGB')
+
+        # 准备消息格式
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "image": pil_image,
+                    },
+                    {"type": "text", "text": question},
+                ],
+            }
+        ]
+
+        # 处理输入
+        text = processor.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True
+        )
+        image_inputs, video_inputs = process_vision_info(messages)
+        inputs = processor(
+            text=[text],
+            images=image_inputs,
+            videos=video_inputs,
+            padding=True,
+            return_tensors="pt",
+        )
+
+        # 生成回答
+        with torch.no_grad():
+            generated_ids = model.generate(
+                **inputs,
+                max_new_tokens=512,
+                do_sample=False,
+                temperature=0.7,
+                top_p=0.9,
+                pad_token_id=processor.tokenizer.eos_token_id
+            )
+
+        generated_ids_trimmed = [
+            out_ids[len(in_ids):] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
+        ]
+
+        output_text = processor.batch_decode(
+            generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
+        )[0]
+
+        return {
+            "success": True,
+            "question": question,
+            "answer": output_text,
+            "image_info": {
+                "filename": image.filename,
+                "size": f"{pil_image.size[0]}x{pil_image.size[1]}",
+                "mode": pil_image.mode
+            }
+        }
+
+    except Exception as e:
+        logger.error(f"图片分析失败: {str(e)}")
+        return JSONResponse(
+            status_code=500,
+            content={"error": f"图片分析失败: {str(e)}"}
+        )
+
+@app.post("/analyze_image_base64")
+async def analyze_image_base64(
+    image_base64: str = Form(...),
+    question: str = Form("请��述这张图片的内容")
+):
+    """
+    分析 base64 编码的图片并回答问题
+
+    Args:
+        image_base64: base64 编码的图片数据
+        question: 关于图片的问题
+
+    Returns:
+        JSON 响应包含分析结果
+    """
+    if model is None or processor is None:
+        return JSONResponse(
+            status_code=503,
+            content={"error": "模型未加载，请稍后重试"}
+        )
+
+    try:
+        # 解码 base64 图片
+        if image_base64.startswith('data:image'):
+            # 移除 data:image/xxx;base64, 前缀
+            image_base64 = image_base64.split(',')[1]
+
+        image_bytes = base64.b64decode(image_base64)
+        pil_image = Image.open(io.BytesIO(image_bytes))
+
+        # 确保图片是 RGB 格式
+        if pil_image.mode != 'RGB':
+            pil_image = pil_image.convert('RGB')
+
+        # 准备消息格式
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "image": pil_image,
+                    },
+                    {"type": "text", "text": question},
+                ],
+            }
+        ]
+
+        # 处理输入
+        text = processor.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True
+        )
+        image_inputs, video_inputs = process_vision_info(messages)
+        inputs = processor(
+            text=[text],
+            images=image_inputs,
+            videos=video_inputs,
+            padding=True,
+            return_tensors="pt",
+        )
+
+        # 生成回答
+        with torch.no_grad():
+            generated_ids = model.generate(
+                **inputs,
+                max_new_tokens=512,
+                do_sample=False,
+                temperature=0.7,
+                top_p=0.9,
+                pad_token_id=processor.tokenizer.eos_token_id
+            )
+
+        generated_ids_trimmed = [
+            out_ids[len(in_ids):] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
+        ]
+
+        output_text = processor.batch_decode(
+            generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
+        )[0]
+
+        return {
+            "success": True,
+            "question": question,
+            "answer": output_text,
+            "image_info": {
+                "size": f"{pil_image.size[0]}x{pil_image.size[1]}",
+                "mode": pil_image.mode
+            }
+        }
+
+    except Exception as e:
+        logger.error(f"图片分析失败: {str(e)}")
+        return JSONResponse(
+            status_code=500,
+            content={"error": f"图片分析失败: {str(e)}"}
+        )
+
+@app.post("/analyze", response_model=AnalyzeResponse)
+async def analyze_simple(request: AnalyzeRequest):
+    """
+    简化的图片分析接口 (JSON 格式)
+
+    接收 JSON 格式的请求，包含 base64 图片和提示词
+    返回标准化的分析结果
+    """
+    if model is None or processor is None:
+        return AnalyzeResponse(
+            success=False,
+            prompt=request.prompt,
+            response="",
+            processing_time=0,
+            error="模型未加载，请稍后重试"
+        )
+
+    start_time = time.time()
+
+    try:
+        # 处理 base64 图片
+        image_data = request.image
+        if image_data.startswith('data:image'):
+            # 移除 data:image/xxx;base64, 前缀
+            image_data = image_data.split(',')[1]
+
+        image_bytes = base64.b64decode(image_data)
+        pil_image = Image.open(io.BytesIO(image_bytes))
+
+        # 确保图片是 RGB 格式
+        if pil_image.mode != 'RGB':
+            pil_image = pil_image.convert('RGB')
+
+        # 准备消息格式
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "image": pil_image,
+                    },
+                    {"type": "text", "text": request.prompt},
+                ],
+            }
+        ]
+
+        # 处理输入
+        text = processor.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True
+        )
+        image_inputs, video_inputs = process_vision_info(messages)
+        inputs = processor(
+            text=[text],
+            images=image_inputs,
+            videos=video_inputs,
+            padding=True,
+            return_tensors="pt",
+        )
+
+        # 生成回答
+        with torch.no_grad():
+            generated_ids = model.generate(
+                **inputs,
+                max_new_tokens=512,
+                do_sample=False,
+                temperature=0.7,
+                top_p=0.9,
+                pad_token_id=processor.tokenizer.eos_token_id
+            )
+
+        generated_ids_trimmed = [
+            out_ids[len(in_ids):] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
+        ]
+
+        output_text = processor.batch_decode(
+            generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
+        )[0]
+
+        processing_time = time.time() - start_time
+
+        return AnalyzeResponse(
+            success=True,
+            prompt=request.prompt,
+            response=output_text,
+            processing_time=processing_time,
+            image_info={
+                "size": f"{pil_image.size[0]}x{pil_image.size[1]}",
+                "mode": pil_image.mode,
+                "format": pil_image.format or "Unknown"
+            }
+        )
+
+    except Exception as e:
+        processing_time = time.time() - start_time
+        logger.error(f"图片分析失败: {str(e)}")
+
+        return AnalyzeResponse(
+            success=False,
+            prompt=request.prompt,
+            response="",
+            processing_time=processing_time,
+            error=f"图片分析失败: {str(e)}"
+        )
+
+@app.get("/memory_status")
+def get_memory_status():
+    """获取当前内存使用状态"""
+    try:
+        # 系统内存信息
+        memory = psutil.virtual_memory()
+
+        # PyTorch 内存信息（如果使用 CUDA）
+        torch_memory = {}
+        if torch.cuda.is_available():
+            torch_memory = {
+                "cuda_allocated": torch.cuda.memory_allocated() / 1024**3,  # GB
+                "cuda_reserved": torch.cuda.memory_reserved() / 1024**3,    # GB
+                "cuda_max_allocated": torch.cuda.max_memory_allocated() / 1024**3,  # GB
+            }
+
+        return {
+            "system_memory": {
+                "total_gb": memory.total / 1024**3,
+                "available_gb": memory.available / 1024**3,
+                "used_gb": memory.used / 1024**3,
+                "percent": memory.percent
+            },
+            "torch_memory": torch_memory,
+            "model_loaded": model is not None,
+            "recommendations": {
+                "memory_usage_ok": memory.percent < 85,
+                "available_for_inference": memory.available / 1024**3 > 2.0
+            }
+        }
+    except Exception as e:
+        return JSONResponse(
+            status_code=500,
+            content={"error": f"获取内存状态失败: {str(e)}"}
+        )
+
+@app.post("/clear_cache")
+def clear_cache():
+    """清理内存缓存"""
+    try:
+        # Python 垃圾回收
+        gc.collect()
+
+        # PyTorch 缓存清理
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+        return {"success": True, "message": "缓存清理完成"}
+    except Exception as e:
+        return JSONResponse(
+            status_code=500,
+            content={"error": f"缓存清理失败: {str(e)}"}
+        )
+
+@app.get("/web")
+def web_interface():
+    """返回 Web 界面"""
+    return FileResponse("static/index.html")

example_usage.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""
+PicExam API 使用示例
+演示如何通过不同方式调用 Qwen-VL 图像分析 API
+"""
+
+import requests
+import base64
+import json
+from PIL import Image
+import io
+
+# API 基础 URL
+BASE_URL = "http://localhost:7860"
+
+def create_sample_image():
+    """创建一个示例图片用于测试"""
+    # 创建一个简单的测试图片
+    img = Image.new('RGB', (300, 200), color='lightblue')
+    
+    # 添加一些图形
+    from PIL import ImageDraw, ImageFont
+    draw = ImageDraw.Draw(img)
+    
+    # 绘制矩形
+    draw.rectangle([50, 50, 150, 100], fill='red', outline='black', width=2)
+    
+    # 绘制圆形
+    draw.ellipse([180, 60, 250, 130], fill='yellow', outline='black', width=2)
+    
+    # 添加文字
+    try:
+        # 尝试使用默认字体
+        draw.text((100, 150), "Sample Image", fill='black')
+    except:
+        # 如果没有字体，跳过文字
+        pass
+    
+    return img
+
+def image_to_base64(image):
+    """将 PIL 图片转换为 base64 字符串"""
+    buffer = io.BytesIO()
+    image.save(buffer, format='PNG')
+    img_str = base64.b64encode(buffer.getvalue()).decode()
+    return f"data:image/png;base64,{img_str}"
+
+def test_api_info():
+    """测试 API 信息获取"""
+    print("🔍 获取 API 信息...")
+    try:
+        response = requests.get(f"{BASE_URL}/")
+        if response.status_code == 200:
+            data = response.json()
+            print(f"✅ 服务: {data['service']}")
+            print(f"✅ 版本: {data['version']}")
+            print(f"✅ 模型: {data['model']}")
+            print(f"✅ 模型状态: {'已加载' if data['status']['model_loaded'] else '未加载'}")
+            print(f"✅ 可用端点数量: {len(data['endpoints'])}")
+            return True
+        else:
+            print(f"❌ 获取 API 信息失败: {response.status_code}")
+            return False
+    except Exception as e:
+        print(f"❌ 连接失败: {e}")
+        return False
+
+def test_health_check():
+    """测试健康检查"""
+    print("\n🔍 健康检查...")
+    try:
+        response = requests.get(f"{BASE_URL}/health")
+        if response.status_code == 200:
+            data = response.json()
+            print(f"✅ 状态: {data['status']}")
+            print(f"✅ 模型: {'已加载' if data['model_loaded'] else '未加载'}")
+            return True
+        else:
+            print(f"❌ 健康检查失败: {response.status_code}")
+            return False
+    except Exception as e:
+        print(f"❌ 健康检查异常: {e}")
+        return False
+
+def test_file_upload():
+    """测试文件上传方式"""
+    print("\n🔍 测试文件上传分析...")
+    
+    # 创建测试图片
+    test_img = create_sample_image()
+    test_img.save("temp_test.png")
+    
+    try:
+        with open("temp_test.png", "rb") as f:
+            files = {"image": ("test.png", f, "image/png")}
+            data = {"question": "请描述这张图片中的颜色和形状"}
+            
+            response = requests.post(f"{BASE_URL}/analyze_image", files=files, data=data)
+            
+            if response.status_code == 200:
+                result = response.json()
+                print(f"✅ 分析成功!")
+                print(f"   问题: {result['question']}")
+                print(f"   回答: {result['answer']}")
+                print(f"   图片信息: {result['image_info']}")
+                return True
+            else:
+                print(f"❌ 文件上传分析失败: {response.status_code}")
+                print(f"   错误: {response.text}")
+                return False
+                
+    except Exception as e:
+        print(f"❌ 文件上传测试异常: {e}")
+        return False
+    finally:
+        # 清理临时文件
+        try:
+            import os
+            os.remove("temp_test.png")
+        except:
+            pass
+
+def test_base64_form():
+    """测试 base64 表单方式"""
+    print("\n🔍 测试 base64 表单分析...")
+    
+    try:
+        # 创建测试图片并转换为 base64
+        test_img = create_sample_image()
+        img_base64 = image_to_base64(test_img)
+        
+        data = {
+            "image_base64": img_base64,
+            "question": "这张图片中有什么几何形状？"
+        }
+        
+        response = requests.post(f"{BASE_URL}/analyze_image_base64", data=data)
+        
+        if response.status_code == 200:
+            result = response.json()
+            print(f"✅ 分析成功!")
+            print(f"   问题: {result['question']}")
+            print(f"   回答: {result['answer']}")
+            print(f"   图片信息: {result['image_info']}")
+            return True
+        else:
+            print(f"❌ base64 表单分析失败: {response.status_code}")
+            print(f"   错误: {response.text}")
+            return False
+            
+    except Exception as e:
+        print(f"❌ base64 表单测试异常: {e}")
+        return False
+
+def test_json_api():
+    """测试 JSON API 方式"""
+    print("\n🔍 测试 JSON API 分析...")
+    
+    try:
+        # 创建测试图片并转换为 base64
+        test_img = create_sample_image()
+        img_base64 = image_to_base64(test_img)
+        
+        request_data = {
+            "image": img_base64,
+            "prompt": "请详细分析这张图片的构成元素，包括颜色、形状和布局"
+        }
+        
+        response = requests.post(
+            f"{BASE_URL}/analyze",
+            headers={"Content-Type": "application/json"},
+            json=request_data
+        )
+        
+        if response.status_code == 200:
+            result = response.json()
+            print(f"✅ 分析成功!")
+            print(f"   提示词: {result['prompt']}")
+            print(f"   响应: {result['response']}")
+            print(f"   处理时间: {result['processing_time']:.2f}秒")
+            print(f"   图片信息: {result['image_info']}")
+            return True
+        else:
+            print(f"❌ JSON API 分析失败: {response.status_code}")
+            print(f"   错误: {response.text}")
+            return False
+            
+    except Exception as e:
+        print(f"❌ JSON API 测试异常: {e}")
+        return False
+
+def test_memory_status():
+    """测试内存状态"""
+    print("\n🔍 检查内存状态...")
+    try:
+        response = requests.get(f"{BASE_URL}/memory_status")
+        if response.status_code == 200:
+            data = response.json()
+            memory = data['system_memory']
+            print(f"✅ 系统内存: {memory['used_gb']:.2f}GB / {memory['total_gb']:.2f}GB ({memory['percent']:.1f}%)")
+            print(f"✅ 可用内存: {memory['available_gb']:.2f}GB")
+            print(f"✅ 内存状态: {'正常' if data['recommendations']['memory_usage_ok'] else '紧张'}")
+            return True
+        else:
+            print(f"❌ 内存状态检查失败: {response.status_code}")
+            return False
+    except Exception as e:
+        print(f"❌ 内存状态检查异常: {e}")
+        return False
+
+def main():
+    """主测试函数"""
+    print("🚀 PicExam API 使用示例")
+    print("=" * 60)
+    
+    tests = [
+        ("API 信息获取", test_api_info),
+        ("健康检查", test_health_check),
+        ("内存状态", test_memory_status),
+        ("文件上传分析", test_file_upload),
+        ("Base64 表单分析", test_base64_form),
+        ("JSON API 分析", test_json_api),
+    ]
+    
+    results = []
+    for test_name, test_func in tests:
+        try:
+            result = test_func()
+            results.append((test_name, result))
+            if result:
+                print(f"✅ {test_name} - 成功")
+            else:
+                print(f"❌ {test_name} - 失败")
+        except Exception as e:
+            print(f"❌ {test_name} - 异常: {e}")
+            results.append((test_name, False))
+        
+        print("-" * 40)
+    
+    # 总结
+    print("\n📊 测试结果总结:")
+    passed = sum(1 for _, result in results if result)
+    total = len(results)
+    
+    for test_name, result in results:
+        status = "✅ 通过" if result else "❌ 失败"
+        print(f"  {test_name}: {status}")
+    
+    print(f"\n总计: {passed}/{total} 测试通过")
+    
+    if passed == total:
+        print("🎉 所有测试都通过了！API 运行正常。")
+        print("\n💡 使用提示:")
+        print(f"  - Web 界面: {BASE_URL}/web")
+        print(f"  - API 文档: {BASE_URL}/docs")
+        print(f"  - API 信息: {BASE_URL}/")
+    else:
+        print("⚠️  部分测试失败，请检查服务状态。")
+
+if __name__ == "__main__":
+    main()

quick_test.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""
+快速测试脚本 - 验证 PicExam API 的核心功能
+"""
+
+import requests
+import time
+import json
+
+def wait_for_service(max_wait=60):
+    """等待服务启动"""
+    print("⏳ 等待服务启动...")
+    start_time = time.time()
+    
+    while time.time() - start_time < max_wait:
+        try:
+            response = requests.get("http://localhost:7860/health", timeout=5)
+            if response.status_code == 200:
+                print("✅ 服务已启动")
+                return True
+        except:
+            pass
+        
+        print(".", end="", flush=True)
+        time.sleep(2)
+    
+    print("\n❌ 服务启动超时")
+    return False
+
+def test_endpoints():
+    """测试主要端点"""
+    print("\n🔍 测试 API 端点...")
+    
+    endpoints = [
+        ("GET /", "API 信息"),
+        ("GET /health", "健康检查"),
+        ("GET /memory_status", "内存状态"),
+        ("GET /web", "Web 界面"),
+        ("GET /docs", "API 文档")
+    ]
+    
+    results = []
+    for endpoint, description in endpoints:
+        try:
+            method, path = endpoint.split(" ", 1)
+            url = f"http://localhost:7860{path}"
+            
+            if method == "GET":
+                response = requests.get(url, timeout=10)
+            
+            if response.status_code == 200:
+                print(f"✅ {endpoint} - {description}")
+                results.append(True)
+            else:
+                print(f"❌ {endpoint} - {description} (状态码: {response.status_code})")
+                results.append(False)
+                
+        except Exception as e:
+            print(f"❌ {endpoint} - {description} (错误: {e})")
+            results.append(False)
+    
+    return results
+
+def show_api_info():
+    """显示 API 信息"""
+    print("\n📋 API 信息:")
+    try:
+        response = requests.get("http://localhost:7860/")
+        if response.status_code == 200:
+            data = response.json()
+            print(f"  服务: {data['service']}")
+            print(f"  版本: {data['version']}")
+            print(f"  模型: {data['model']}")
+            print(f"  状态: {'✅ 模型已加载' if data['status']['model_loaded'] else '⏳ 模型加载中'}")
+            print(f"  推理模式: {data['status']['inference_mode']}")
+            
+            print(f"\n📚 可用端点 ({len(data['endpoints'])} 个):")
+            for endpoint, info in data['endpoints'].items():
+                print(f"  {endpoint}: {info['description']}")
+            
+            return True
+        else:
+            print("❌ 无法获取 API 信息")
+            return False
+    except Exception as e:
+        print(f"❌ 获取 API 信息失败: {e}")
+        return False
+
+def show_usage_examples():
+    """显示使用示例"""
+    print("\n💡 使用示例:")
+    print("=" * 50)
+    
+    examples = [
+        {
+            "title": "1. 浏览器访问",
+            "commands": [
+                "Web 界面: http://localhost:7860/web",
+                "API 文档: http://localhost:7860/docs",
+                "API 信息: http://localhost:7860/"
+            ]
+        },
+        {
+            "title": "2. 文件上传分析",
+            "commands": [
+                "curl -X POST 'http://localhost:7860/analyze_image' \\",
+                "  -F 'image=@your_image.jpg' \\",
+                "  -F 'question=请描述这张图片'"
+            ]
+        },
+        {
+            "title": "3. Base64 图片分析",
+            "commands": [
+                "curl -X POST 'http://localhost:7860/analyze_image_base64' \\",
+                "  -F 'image_base64=data:image/jpeg;base64,/9j/4AAQ...' \\",
+                "  -F 'question=这张图片中有什么？'"
+            ]
+        },
+        {
+            "title": "4. JSON API 调用",
+            "commands": [
+                "curl -X POST 'http://localhost:7860/analyze' \\",
+                "  -H 'Content-Type: application/json' \\",
+                "  -d '{\"image\":\"data:image/jpeg;base64,...\",\"prompt\":\"描述图片\"}'",
+            ]
+        },
+        {
+            "title": "5. Python 调用示例",
+            "commands": [
+                "python example_usage.py  # 运行完整示例",
+                "python test_api.py       # 运行详细测试"
+            ]
+        }
+    ]
+    
+    for example in examples:
+        print(f"\n{example['title']}:")
+        for cmd in example['commands']:
+            print(f"  {cmd}")
+
+def main():
+    """主函数"""
+    print("🚀 PicExam API 快速测试")
+    print("=" * 50)
+    
+    # 等待服务启动
+    if not wait_for_service():
+        print("❌ 服务未启动，请先运行:")
+        print("  python start_local.py")
+        print("  或")
+        print("  uvicorn app:app --host 0.0.0.0 --port 7860")
+        return
+    
+    # 显示 API 信息
+    show_api_info()
+    
+    # 测试端点
+    results = test_endpoints()
+    
+    # 显示测试结果
+    passed = sum(results)
+    total = len(results)
+    print(f"\n📊 端点测试结果: {passed}/{total} 通过")
+    
+    if passed == total:
+        print("🎉 所有基础端点都正常工作！")
+    else:
+        print("⚠️  部分端点可能有问题")
+    
+    # 显示使用示例
+    show_usage_examples()
+    
+    print("\n" + "=" * 50)
+    print("✨ 快速测试完成！")
+    print("💡 提示: 运行 'python example_usage.py' 进行完整的功能测试")
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -1,2 +1,10 @@
 fastapi
 uvicorn[standard]
+torch>=2.0.0
+transformers>=4.37.0
+accelerate
+qwen-vl-utils
+Pillow
+requests
+numpy
+psutil

start_local.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+本地启动 Qwen-VL PicExam API 的脚本
+适用于 16GB 内存 + CPU 推理环境
+"""
+
+import subprocess
+import sys
+import os
+import time
+import psutil
+
+def check_memory():
+    """检查系统内存是否足够"""
+    memory = psutil.virtual_memory()
+    total_gb = memory.total / 1024**3
+    available_gb = memory.available / 1024**3
+    
+    print(f"💾 系统内存状态:")
+    print(f"   总内存: {total_gb:.1f}GB")
+    print(f"   可用内存: {available_gb:.1f}GB")
+    print(f"   使用率: {memory.percent:.1f}%")
+    
+    if total_gb < 15:
+        print("⚠️  警告: 系统内存少于 16GB，可能影响模型运行")
+        return False
+    
+    if available_gb < 8:
+        print("⚠️  警告: 可用内存少于 8GB，建议关闭其他程序")
+        return False
+    
+    print("✅ 内存检查通过")
+    return True
+
+def install_dependencies():
+    """安装依赖包"""
+    print("📦 安装依赖包...")
+    try:
+        subprocess.check_call([sys.executable, "-m", "pip", "install", "-r", "requirements.txt"])
+        print("✅ 依赖包安装完成")
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"❌ 依赖包安装失败: {e}")
+        return False
+
+def start_server():
+    """启动服务器"""
+    print("🚀 启动 Qwen-VL PicExam API 服务器...")
+    print("📝 注意: 首次启动会下载模型，可能需要较长时间")
+    print("🔗 服务器启动后可访问: http://localhost:7860")
+    print("📚 API 文档: http://localhost:7860/docs")
+    print("-" * 50)
+    
+    try:
+        # 设置环境变量
+        env = os.environ.copy()
+        env["PYTORCH_CUDA_ALLOC_CONF"] = "max_split_size_mb:512"
+        env["TOKENIZERS_PARALLELISM"] = "false"
+        env["OMP_NUM_THREADS"] = "4"
+        env["MKL_NUM_THREADS"] = "4"
+        
+        # 启动服务器
+        subprocess.run([
+            sys.executable, "-m", "uvicorn", 
+            "app:app", 
+            "--host", "0.0.0.0", 
+            "--port", "7860",
+            "--reload",
+            "--timeout-keep-alive", "300"
+        ], env=env)
+        
+    except KeyboardInterrupt:
+        print("\n🛑 服务器已停止")
+    except Exception as e:
+        print(f"❌ 服务器启动失败: {e}")
+
+def main():
+    """主函数"""
+    print("🤖 Qwen-VL PicExam API 本地启动器")
+    print("=" * 50)
+    print("📋 配置信息:")
+    print("   - 模型: Qwen2-VL-2B-Instruct")
+    print("   - 推理: CPU 模式")
+    print("   - 内存优化: 启用")
+    print("   - 端口: 7860")
+    print("=" * 50)
+    
+    # 检查内存
+    if not check_memory():
+        response = input("是否继续启动? (y/N): ")
+        if response.lower() != 'y':
+            print("启动已取消")
+            return
+    
+    # 安装依赖
+    if not install_dependencies():
+        print("❌ 无法安装依赖，启动失败")
+        return
+    
+    # 启动服务器
+    start_server()
+
+if __name__ == "__main__":
+    main()

static/index.html

@@ -0,0 +1,552 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>PicExam - Qwen-VL 图像理解</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+        
+        body {
+            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            min-height: 100vh;
+            padding: 20px;
+        }
+        
+        .container {
+            max-width: 800px;
+            margin: 0 auto;
+            background: white;
+            border-radius: 15px;
+            box-shadow: 0 20px 40px rgba(0,0,0,0.1);
+            overflow: hidden;
+        }
+        
+        .header {
+            background: linear-gradient(135deg, #ff6b6b, #ee5a24);
+            color: white;
+            padding: 30px;
+            text-align: center;
+        }
+        
+        .header h1 {
+            font-size: 2.5em;
+            margin-bottom: 10px;
+        }
+        
+        .header p {
+            font-size: 1.1em;
+            opacity: 0.9;
+        }
+        
+        .content {
+            padding: 30px;
+        }
+        
+        .upload-area {
+            border: 3px dashed #ddd;
+            border-radius: 10px;
+            padding: 40px;
+            text-align: center;
+            margin-bottom: 20px;
+            transition: all 0.3s ease;
+            cursor: pointer;
+        }
+        
+        .upload-area:hover {
+            border-color: #667eea;
+            background-color: #f8f9ff;
+        }
+        
+        .upload-area.dragover {
+            border-color: #667eea;
+            background-color: #f0f2ff;
+        }
+        
+        .upload-icon {
+            font-size: 3em;
+            color: #ddd;
+            margin-bottom: 15px;
+        }
+        
+        .form-group {
+            margin-bottom: 20px;
+        }
+        
+        label {
+            display: block;
+            margin-bottom: 8px;
+            font-weight: 600;
+            color: #333;
+        }
+        
+        input[type="file"], textarea {
+            width: 100%;
+            padding: 12px;
+            border: 2px solid #ddd;
+            border-radius: 8px;
+            font-size: 16px;
+            transition: border-color 0.3s ease;
+        }
+        
+        input[type="file"]:focus, textarea:focus {
+            outline: none;
+            border-color: #667eea;
+        }
+        
+        textarea {
+            resize: vertical;
+            min-height: 80px;
+        }
+        
+        .btn {
+            background: linear-gradient(135deg, #667eea, #764ba2);
+            color: white;
+            border: none;
+            padding: 15px 30px;
+            border-radius: 8px;
+            font-size: 16px;
+            font-weight: 600;
+            cursor: pointer;
+            transition: all 0.3s ease;
+            width: 100%;
+        }
+        
+        .btn:hover {
+            transform: translateY(-2px);
+            box-shadow: 0 10px 20px rgba(102, 126, 234, 0.3);
+        }
+        
+        .btn:disabled {
+            background: #ccc;
+            cursor: not-allowed;
+            transform: none;
+            box-shadow: none;
+        }
+        
+        .result {
+            margin-top: 30px;
+            padding: 20px;
+            background: #f8f9fa;
+            border-radius: 10px;
+            border-left: 5px solid #667eea;
+        }
+        
+        .result h3 {
+            color: #333;
+            margin-bottom: 15px;
+        }
+        
+        .result-content {
+            background: white;
+            padding: 15px;
+            border-radius: 8px;
+            border: 1px solid #e9ecef;
+        }
+        
+        .loading {
+            display: none;
+            text-align: center;
+            padding: 20px;
+        }
+        
+        .spinner {
+            border: 4px solid #f3f3f3;
+            border-top: 4px solid #667eea;
+            border-radius: 50%;
+            width: 40px;
+            height: 40px;
+            animation: spin 1s linear infinite;
+            margin: 0 auto 15px;
+        }
+        
+        @keyframes spin {
+            0% { transform: rotate(0deg); }
+            100% { transform: rotate(360deg); }
+        }
+        
+        .error {
+            background: #ffe6e6;
+            border-left-color: #ff4757;
+            color: #c44569;
+        }
+        
+        .preview-image {
+            max-width: 100%;
+            max-height: 300px;
+            border-radius: 8px;
+            margin: 15px 0;
+            box-shadow: 0 5px 15px rgba(0,0,0,0.1);
+        }
+        
+        .status-bar {
+            background: #f8f9fa;
+            padding: 15px;
+            border-radius: 8px;
+            margin-bottom: 20px;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+        }
+        
+        .status-indicator {
+            display: flex;
+            align-items: center;
+            gap: 8px;
+        }
+        
+        .status-dot {
+            width: 10px;
+            height: 10px;
+            border-radius: 50%;
+            background: #28a745;
+        }
+        
+        .status-dot.loading {
+            background: #ffc107;
+            animation: pulse 1.5s infinite;
+        }
+        
+        .status-dot.error {
+            background: #dc3545;
+        }
+        
+        @keyframes pulse {
+            0%, 100% { opacity: 1; }
+            50% { opacity: 0.5; }
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="header">
+            <h1>🏆 PicExam</h1>
+            <p>基于 Qwen-VL 的智能图像理解系统</p>
+            <div style="margin-top: 15px; font-size: 0.9em;">
+                <a href="/docs" style="color: white; text-decoration: none; margin-right: 15px;">📚 API 文档</a>
+                <a href="/" style="color: white; text-decoration: none; margin-right: 15px;">🔗 API 端点</a>
+                <a href="/memory_status" style="color: white; text-decoration: none;">💾 内存状态</a>
+            </div>
+        </div>
+        
+        <div class="content">
+            <div class="status-bar">
+                <div class="status-indicator">
+                    <div class="status-dot" id="statusDot"></div>
+                    <span id="statusText">检查服务状态...</span>
+                </div>
+                <button onclick="checkStatus()" style="background: none; border: 1px solid #ddd; padding: 5px 10px; border-radius: 5px; cursor: pointer;">刷新</button>
+            </div>
+            
+            <form id="uploadForm">
+                <div class="form-group">
+                    <label for="imageFile">选择图片</label>
+                    <div class="upload-area" id="uploadArea">
+                        <div class="upload-icon">📷</div>
+                        <p>点击选择图片或拖拽图片到此处</p>
+                        <p style="font-size: 0.9em; color: #666; margin-top: 10px;">支持 JPG, PNG, WebP 格式</p>
+                    </div>
+                    <input type="file" id="imageFile" accept="image/*" style="display: none;">
+                    <img id="previewImage" class="preview-image" style="display: none;">
+                </div>
+                
+                <div class="form-group">
+                    <label for="question">问题描述</label>
+                    <textarea id="question" placeholder="请输入您想问的关于图片的问题，例如：请描述这张图片的内容、图片中有什么物体、图片的颜色如何等...">请描述这张图片的内容</textarea>
+                </div>
+                
+                <button type="submit" class="btn" id="submitBtn">
+                    🔍 分析图片
+                </button>
+            </form>
+            
+            <div class="loading" id="loading">
+                <div class="spinner"></div>
+                <p>正在分析图片，请稍候...</p>
+            </div>
+            
+            <div id="result" style="display: none;"></div>
+
+            <!-- API 测试区域 -->
+            <div style="margin-top: 40px; padding-top: 30px; border-top: 2px solid #eee;">
+                <h2 style="color: #333; margin-bottom: 20px;">🔧 API 测试工具</h2>
+
+                <div style="background: #f8f9fa; padding: 20px; border-radius: 10px; margin-bottom: 20px;">
+                    <h3 style="color: #555; margin-bottom: 15px;">JSON API 测试 (/analyze)</h3>
+                    <div style="margin-bottom: 15px;">
+                        <label style="display: block; margin-bottom: 5px; font-weight: 600;">提示词:</label>
+                        <input type="text" id="jsonPrompt" value="请详细描述这张图片的内容" style="width: 100%; padding: 8px; border: 1px solid #ddd; border-radius: 5px;">
+                    </div>
+                    <button onclick="testJsonAPI()" style="background: #28a745; color: white; border: none; padding: 10px 20px; border-radius: 5px; cursor: pointer;">测试 JSON API</button>
+                    <div id="jsonResult" style="margin-top: 15px; display: none;"></div>
+                </div>
+
+                <div style="background: #f8f9fa; padding: 20px; border-radius: 10px;">
+                    <h3 style="color: #555; margin-bottom: 15px;">API 端点信息</h3>
+                    <button onclick="showAPIInfo()" style="background: #17a2b8; color: white; border: none; padding: 10px 20px; border-radius: 5px; cursor: pointer;">获取 API 信息</button>
+                    <div id="apiInfo" style="margin-top: 15px; display: none;"></div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script>
+        // 检查服务状态
+        async function checkStatus() {
+            const statusDot = document.getElementById('statusDot');
+            const statusText = document.getElementById('statusText');
+            
+            statusDot.className = 'status-dot loading';
+            statusText.textContent = '检查中...';
+            
+            try {
+                const response = await fetch('/');
+                const data = await response.json();
+                
+                if (data.model_loaded) {
+                    statusDot.className = 'status-dot';
+                    statusText.textContent = '服务正常，模型已加载';
+                } else {
+                    statusDot.className = 'status-dot error';
+                    statusText.textContent = '服务运行中，模型加载中...';
+                }
+            } catch (error) {
+                statusDot.className = 'status-dot error';
+                statusText.textContent = '服务连接失败';
+            }
+        }
+        
+        // 页面加载时检查状态
+        window.addEventListener('load', checkStatus);
+        
+        // 文件上传处理
+        const uploadArea = document.getElementById('uploadArea');
+        const fileInput = document.getElementById('imageFile');
+        const previewImage = document.getElementById('previewImage');
+        
+        uploadArea.addEventListener('click', () => fileInput.click());
+        
+        uploadArea.addEventListener('dragover', (e) => {
+            e.preventDefault();
+            uploadArea.classList.add('dragover');
+        });
+        
+        uploadArea.addEventListener('dragleave', () => {
+            uploadArea.classList.remove('dragover');
+        });
+        
+        uploadArea.addEventListener('drop', (e) => {
+            e.preventDefault();
+            uploadArea.classList.remove('dragover');
+            
+            const files = e.dataTransfer.files;
+            if (files.length > 0) {
+                fileInput.files = files;
+                handleFileSelect();
+            }
+        });
+        
+        fileInput.addEventListener('change', handleFileSelect);
+        
+        function handleFileSelect() {
+            const file = fileInput.files[0];
+            if (file) {
+                const reader = new FileReader();
+                reader.onload = (e) => {
+                    previewImage.src = e.target.result;
+                    previewImage.style.display = 'block';
+                    uploadArea.innerHTML = `
+                        <div class="upload-icon">✅</div>
+                        <p>已选择: ${file.name}</p>
+                        <p style="font-size: 0.9em; color: #666;">点击重新选择</p>
+                    `;
+                };
+                reader.readAsDataURL(file);
+            }
+        }
+        
+        // 表单提交处理
+        document.getElementById('uploadForm').addEventListener('submit', async (e) => {
+            e.preventDefault();
+            
+            const file = fileInput.files[0];
+            const question = document.getElementById('question').value;
+            
+            if (!file) {
+                alert('请先选择一张图片');
+                return;
+            }
+            
+            const submitBtn = document.getElementById('submitBtn');
+            const loading = document.getElementById('loading');
+            const result = document.getElementById('result');
+            
+            // 显示加载状态
+            submitBtn.disabled = true;
+            loading.style.display = 'block';
+            result.style.display = 'none';
+            
+            try {
+                const formData = new FormData();
+                formData.append('image', file);
+                formData.append('question', question);
+                
+                const response = await fetch('/analyze_image', {
+                    method: 'POST',
+                    body: formData
+                });
+                
+                const data = await response.json();
+                
+                if (data.success) {
+                    result.innerHTML = `
+                        <div class="result">
+                            <h3>📝 分析结果</h3>
+                            <div class="result-content">
+                                <p><strong>问题:</strong> ${data.question}</p>
+                                <p><strong>回答:</strong> ${data.answer}</p>
+                                <p><strong>图片信息:</strong> ${data.image_info.filename} (${data.image_info.size})</p>
+                            </div>
+                        </div>
+                    `;
+                } else {
+                    throw new Error(data.error || '分析失败');
+                }
+            } catch (error) {
+                result.innerHTML = `
+                    <div class="result error">
+                        <h3>❌ 分析失败</h3>
+                        <div class="result-content">
+                            <p>${error.message}</p>
+                        </div>
+                    </div>
+                `;
+            } finally {
+                submitBtn.disabled = false;
+                loading.style.display = 'none';
+                result.style.display = 'block';
+            }
+        });
+
+        // JSON API 测试
+        async function testJsonAPI() {
+            const file = fileInput.files[0];
+            const prompt = document.getElementById('jsonPrompt').value;
+            const resultDiv = document.getElementById('jsonResult');
+
+            if (!file) {
+                alert('请先选择一张图片');
+                return;
+            }
+
+            try {
+                // 将图片转换为 base64
+                const base64 = await fileToBase64(file);
+
+                const requestData = {
+                    image: base64,
+                    prompt: prompt
+                };
+
+                resultDiv.innerHTML = '<p>🔄 正在调用 JSON API...</p>';
+                resultDiv.style.display = 'block';
+
+                const response = await fetch('/analyze', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json'
+                    },
+                    body: JSON.stringify(requestData)
+                });
+
+                const data = await response.json();
+
+                if (data.success) {
+                    resultDiv.innerHTML = `
+                        <div style="background: #d4edda; border: 1px solid #c3e6cb; padding: 15px; border-radius: 5px;">
+                            <h4 style="color: #155724; margin-bottom: 10px;">✅ JSON API 调用成功</h4>
+                            <p><strong>提示词:</strong> ${data.prompt}</p>
+                            <p><strong>响应:</strong> ${data.response}</p>
+                            <p><strong>处理时间:</strong> ${data.processing_time.toFixed(2)}秒</p>
+                            <p><strong>图片信息:</strong> ${data.image_info.size} (${data.image_info.mode})</p>
+                        </div>
+                    `;
+                } else {
+                    resultDiv.innerHTML = `
+                        <div style="background: #f8d7da; border: 1px solid #f5c6cb; padding: 15px; border-radius: 5px;">
+                            <h4 style="color: #721c24; margin-bottom: 10px;">❌ JSON API 调用失败</h4>
+                            <p><strong>错误:</strong> ${data.error}</p>
+                        </div>
+                    `;
+                }
+            } catch (error) {
+                resultDiv.innerHTML = `
+                    <div style="background: #f8d7da; border: 1px solid #f5c6cb; padding: 15px; border-radius: 5px;">
+                        <h4 style="color: #721c24; margin-bottom: 10px;">❌ 请求失败</h4>
+                        <p><strong>错误:</strong> ${error.message}</p>
+                    </div>
+                `;
+            }
+        }
+
+        // 显示 API 信息
+        async function showAPIInfo() {
+            const infoDiv = document.getElementById('apiInfo');
+
+            try {
+                infoDiv.innerHTML = '<p>🔄 获取 API 信息...</p>';
+                infoDiv.style.display = 'block';
+
+                const response = await fetch('/');
+                const data = await response.json();
+
+                let endpointsHtml = '';
+                for (const [endpoint, info] of Object.entries(data.endpoints)) {
+                    endpointsHtml += `
+                        <div style="margin-bottom: 15px; padding: 10px; background: white; border-radius: 5px; border-left: 3px solid #667eea;">
+                            <h5 style="color: #333; margin-bottom: 5px;">${endpoint}</h5>
+                            <p style="color: #666; margin-bottom: 5px;">${info.description}</p>
+                            ${info.example ? `<code style="background: #f1f1f1; padding: 2px 5px; border-radius: 3px; font-size: 0.9em;">${info.example}</code>` : ''}
+                        </div>
+                    `;
+                }
+
+                infoDiv.innerHTML = `
+                    <div style="background: #e7f3ff; border: 1px solid #b3d9ff; padding: 15px; border-radius: 5px;">
+                        <h4 style="color: #0056b3; margin-bottom: 15px;">📋 API 端点信息</h4>
+                        <p><strong>服务:</strong> ${data.service}</p>
+                        <p><strong>版本:</strong> ${data.version}</p>
+                        <p><strong>模型:</strong> ${data.model}</p>
+                        <p><strong>状态:</strong> ${data.status.model_loaded ? '✅ 模型已加载' : '⏳ 模型加载中'}</p>
+                        <hr style="margin: 15px 0; border: none; border-top: 1px solid #ccc;">
+                        <h5 style="color: #333; margin-bottom: 10px;">可用端点:</h5>
+                        ${endpointsHtml}
+                    </div>
+                `;
+            } catch (error) {
+                infoDiv.innerHTML = `
+                    <div style="background: #f8d7da; border: 1px solid #f5c6cb; padding: 15px; border-radius: 5px;">
+                        <h4 style="color: #721c24; margin-bottom: 10px;">❌ 获取 API 信息失败</h4>
+                        <p><strong>错误:</strong> ${error.message}</p>
+                    </div>
+                `;
+            }
+        }
+
+        // 文件转 base64 工具函数
+        function fileToBase64(file) {
+            return new Promise((resolve, reject) => {
+                const reader = new FileReader();
+                reader.readAsDataURL(file);
+                reader.onload = () => resolve(reader.result);
+                reader.onerror = error => reject(error);
+            });
+        }
+    </script>
+</body>
+</html>

test_api.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""
+测试 Qwen-VL PicExam API 的脚本
+用于验证模型加载和推理功能
+"""
+
+import requests
+import base64
+import json
+import time
+from PIL import Image
+import io
+
+def test_health_check():
+    """测试健康检查接口"""
+    print("🔍 测试健康检查接口...")
+    try:
+        response = requests.get("http://localhost:7860/")
+        print(f"状态码: {response.status_code}")
+        print(f"响应: {response.json()}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"❌ 健康检查失败: {e}")
+        return False
+
+def test_memory_status():
+    """测试内存状态接口"""
+    print("\n🔍 测试内存状态接口...")
+    try:
+        response = requests.get("http://localhost:7860/memory_status")
+        print(f"状态码: {response.status_code}")
+        data = response.json()
+        print(f"系统内存: {data['system_memory']['used_gb']:.2f}GB / {data['system_memory']['total_gb']:.2f}GB ({data['system_memory']['percent']:.1f}%)")
+        print(f"模型已加载: {data['model_loaded']}")
+        print(f"内存使用正常: {data['recommendations']['memory_usage_ok']}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"❌ 内存状态检查失败: {e}")
+        return False
+
+def create_test_image():
+    """创建一个简单的测试图片"""
+    # 创建一个简单的彩色图片
+    img = Image.new('RGB', (200, 200), color='red')
+    
+    # 添加一些简单的图形
+    from PIL import ImageDraw
+    draw = ImageDraw.Draw(img)
+    draw.rectangle([50, 50, 150, 150], fill='blue')
+    draw.ellipse([75, 75, 125, 125], fill='yellow')
+    
+    return img
+
+def image_to_base64(image):
+    """将 PIL 图片转换为 base64 字符串"""
+    buffer = io.BytesIO()
+    image.save(buffer, format='PNG')
+    img_str = base64.b64encode(buffer.getvalue()).decode()
+    return f"data:image/png;base64,{img_str}"
+
+def test_image_analysis():
+    """测试图片分析功能"""
+    print("\n🔍 测试图片分析功能...")
+    
+    # 创建测试图片
+    test_img = create_test_image()
+    
+    # 保存为临时文件
+    test_img.save("test_image.png")
+    
+    try:
+        # 测试文件上传接口
+        print("测试文件上传接口...")
+        with open("test_image.png", "rb") as f:
+            files = {"image": ("test_image.png", f, "image/png")}
+            data = {"question": "请描述这张图片中的颜色和形状"}
+            
+            start_time = time.time()
+            response = requests.post("http://localhost:7860/analyze_image", files=files, data=data)
+            end_time = time.time()
+            
+            print(f"状态码: {response.status_code}")
+            print(f"推理时间: {end_time - start_time:.2f}秒")
+            
+            if response.status_code == 200:
+                result = response.json()
+                print(f"问题: {result['question']}")
+                print(f"回答: {result['answer']}")
+                print(f"图片信息: {result['image_info']}")
+                return True
+            else:
+                print(f"❌ 请求失败: {response.text}")
+                return False
+                
+    except Exception as e:
+        print(f"❌ 图片分析测试失败: {e}")
+        return False
+
+def test_base64_analysis():
+    """测试 base64 图片分析功能"""
+    print("\n🔍 测试 base64 图片分析功能...")
+    
+    try:
+        # 创建测试图片并转换为 base64
+        test_img = create_test_image()
+        img_base64 = image_to_base64(test_img)
+        
+        data = {
+            "image_base64": img_base64,
+            "question": "这张图片中有什么几何形状？"
+        }
+        
+        start_time = time.time()
+        response = requests.post("http://localhost:7860/analyze_image_base64", data=data)
+        end_time = time.time()
+        
+        print(f"状态码: {response.status_code}")
+        print(f"推理时间: {end_time - start_time:.2f}秒")
+        
+        if response.status_code == 200:
+            result = response.json()
+            print(f"问题: {result['question']}")
+            print(f"回答: {result['answer']}")
+            print(f"图片信息: {result['image_info']}")
+            return True
+        else:
+            print(f"❌ 请求失败: {response.text}")
+            return False
+            
+    except Exception as e:
+        print(f"❌ base64 图片分析测试失败: {e}")
+        return False
+
+def test_cache_clear():
+    """测试缓存清理功能"""
+    print("\n🔍 测试缓存清理功能...")
+    try:
+        response = requests.post("http://localhost:7860/clear_cache")
+        print(f"状态码: {response.status_code}")
+        print(f"响应: {response.json()}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"❌ 缓存清理测试失败: {e}")
+        return False
+
+def main():
+    """主测试函数"""
+    print("🚀 开始测试 Qwen-VL PicExam API")
+    print("=" * 50)
+    
+    # 等待服务启动
+    print("⏳ 等待服务启动...")
+    time.sleep(5)
+    
+    tests = [
+        ("健康检查", test_health_check),
+        ("内存状态", test_memory_status),
+        ("图片分析（文件上传）", test_image_analysis),
+        ("图片分析（base64）", test_base64_analysis),
+        ("缓存清理", test_cache_clear),
+    ]
+    
+    results = []
+    for test_name, test_func in tests:
+        try:
+            result = test_func()
+            results.append((test_name, result))
+            if result:
+                print(f"✅ {test_name} 测试通过")
+            else:
+                print(f"❌ {test_name} 测试失败")
+        except Exception as e:
+            print(f"❌ {test_name} 测试异常: {e}")
+            results.append((test_name, False))
+        
+        print("-" * 30)
+    
+    # 总结
+    print("\n📊 测试结果总结:")
+    passed = sum(1 for _, result in results if result)
+    total = len(results)
+    
+    for test_name, result in results:
+        status = "✅ 通过" if result else "❌ 失败"
+        print(f"  {test_name}: {status}")
+    
+    print(f"\n总计: {passed}/{total} 测试通过")
+    
+    if passed == total:
+        print("🎉 所有测试都通过了！API 运行正常。")
+    else:
+        print("⚠️  部分测试失败，请检查日志。")
+
+if __name__ == "__main__":
+    main()