dsh-courseware 0.1.0

package/engine/pptxgen/imagegen.py

@@ -0,0 +1,564 @@
+"""配图生成：可插拔的图像模型后端 + 按 prompt 哈希缓存。
+
+设计要点
+- 不绑定任何一家：`openai-compatible` 适配任意 OpenAI 协议的中转，另附常见国内/国外后端。
+- 按 (后端, 模型, 尺寸, prompt, 风格) 的 sha1 缓存到磁盘，重跑不重复计费。
+- 只用标准库发 HTTP，不引入新依赖。
+- 没有 key 时绝不发请求，而是明确告诉用户该配什么。
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import ssl
+import sys
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+DEFAULT_STYLE = (
+    "儿童科普插画风格，扁平化矢量插画，明亮清爽的配色，构图简洁，主体突出，"
+    "背景干净，画面中不要出现任何文字、字母或数字"
+)
+
+CONFIG_PATHS = [
+    os.path.join(os.getcwd(), ".pptxgen.yaml"),
+    os.path.expanduser("~/.pptxgen/config.yaml"),
+]
+
+
+# --------------------------------------------------------------------------
+# 后端定义
+# --------------------------------------------------------------------------
+@dataclass
+class BackendSpec:
+    name: str
+    label: str
+    kind: str                      # openai | gemini | dashscope | ark
+    base_url: str
+    default_model: str
+    default_size: str
+    key_envs: List[str]
+    supports_size: bool = True
+    alias_of: Optional[str] = None
+
+
+BACKENDS: Dict[str, BackendSpec] = {
+    "openai-compatible": BackendSpec(
+        "openai-compatible", "任意 OpenAI 兼容中转", "openai",
+        "", "", "1024x1024",
+        ["PPTXGEN_IMAGE_API_KEY", "IMAGE_API_KEY", "OPENAI_API_KEY"],
+    ),
+    "openai": BackendSpec(
+        "openai", "OpenAI", "openai",
+        "https://api.openai.com/v1", "gpt-image-1", "1536x1024",
+        ["OPENAI_API_KEY"],
+    ),
+    "qwen": BackendSpec(
+        "qwen", "阿里通义千问 / 百炼", "dashscope",
+        "https://dashscope.aliyuncs.com/api/v1", "qwen-image-2.0-pro", "1328*1328",
+        ["QWEN_API_KEY", "DASHSCOPE_API_KEY"], supports_size=True,
+    ),
+    "zhipu": BackendSpec(
+        "zhipu", "智谱 GLM", "openai",
+        "https://open.bigmodel.cn/api/paas/v4", "glm-image", "1024x1024",
+        ["ZHIPU_API_KEY", "BIGMODEL_API_KEY"],
+    ),
+    "volcengine": BackendSpec(
+        "volcengine", "火山引擎豆包 Seedream", "openai",
+        "https://ark.cn-beijing.volces.com/api/v3", "doubao-seedream-4-5-251128", "1024x1024",
+        ["ARK_API_KEY", "VOLCENGINE_API_KEY", "LAS_API_KEY"],
+    ),
+    "siliconflow": BackendSpec(
+        "siliconflow", "硅基流动", "openai",
+        "https://api.siliconflow.cn/v1", "Qwen/Qwen-Image", "1024x1024",
+        ["SILICONFLOW_API_KEY"],
+    ),
+    "modelscope": BackendSpec(
+        "modelscope", "ModelScope 魔搭", "openai",
+        "https://api-inference.modelscope.cn/v1", "Qwen/Qwen-Image", "1024x1024",
+        ["MODELSCOPE_API_KEY"],
+    ),
+    "gemini": BackendSpec(
+        "gemini", "Google Gemini", "gemini",
+        "https://generativelanguage.googleapis.com/v1beta", "gemini-3.1-flash-image",
+        "1024x1024", ["GEMINI_API_KEY", "GOOGLE_API_KEY"], supports_size=False,
+    ),
+    "openrouter": BackendSpec(
+        "openrouter", "OpenRouter", "openai",
+        "https://openrouter.ai/api/v1", "google/gemini-3.1-flash-image", "1024x1024",
+        ["OPENROUTER_API_KEY"],
+    ),
+    "mock": BackendSpec(
+        "mock", "本地占位图（不联网，仅用于预览排版）", "mock",
+        "local", "placeholder", "1024x1024", [],
+    ),
+    "minimax": BackendSpec(
+        "minimax", "MiniMax", "openai",
+        "https://api.minimax.chat/v1", "image-01", "1024x1024",
+        ["MINIMAX_API_KEY"],
+    ),
+}
+
+
+class ImageGenError(Exception):
+    pass
+
+
+PLACEHOLDER_HINTS = ("your-relay", "example.com", "your-image-model", "xxxxxxxx",
+                     "your-model", "sk-xxxx", "your-key")
+
+
+def _is_placeholder(value) -> bool:
+    """判断一个配置值是不是模板里的占位符。"""
+    if value is None:
+        return True
+    if not isinstance(value, str):
+        return False
+    low = value.strip().lower()
+    if not low:
+        return True
+    return any(h in low for h in PLACEHOLDER_HINTS)
+
+
+# --------------------------------------------------------------------------
+# 配置
+# --------------------------------------------------------------------------
+@dataclass
+class ImageConfig:
+    backend: str = "openai-compatible"
+    api_key: Optional[str] = None
+    base_url: Optional[str] = None
+    model: Optional[str] = None
+    size: Optional[str] = None
+    style: str = DEFAULT_STYLE
+    cache_dir: str = "out/images"
+    timeout: int = 180
+    retries: int = 2
+
+    @property
+    def spec(self) -> BackendSpec:
+        return BACKENDS.get(self.backend) or BACKENDS["openai-compatible"]
+
+
+def load_config(deck_options: Optional[dict] = None) -> ImageConfig:
+    """环境变量 > 课件 options.images > 配置文件。"""
+    # 按顺序合并（先出现的优先），但**占位符不算已定义** ——
+    # 否则工作区里的模板文件会遮蔽用户级配置里的真实值。
+    file_cfg: dict = {}
+    config_sources: list = []
+    for path in CONFIG_PATHS:
+        if not os.path.exists(path):
+            continue
+        try:
+            import yaml
+
+            with open(path, "r", encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+            one = (data.get("images") or data) if isinstance(data, dict) else {}
+            if not isinstance(one, dict):
+                continue
+            used = False
+            for k, v in one.items():
+                if _is_placeholder(v):
+                    continue
+                if k not in file_cfg:
+                    file_cfg[k] = v
+                    used = True
+            config_sources.append(path if used else f"{path}(全是占位符，已忽略)")
+        except Exception:
+            continue
+    load_config.sources = config_sources        # type: ignore[attr-defined]
+    load_config.source = config_sources[0] if config_sources else None  # type: ignore[attr-defined]
+
+    def pick(key: str, env: List[str], default=None):
+        for e in env:
+            v = os.environ.get(e)
+            if v:
+                return v
+        v = (deck_options or {}).get(key)
+        if v:
+            return v
+        return file_cfg.get(key, default)
+
+    cfg = ImageConfig()
+    cfg.backend = pick("backend", ["PPTXGEN_IMAGE_BACKEND"], cfg.backend) or cfg.backend
+    cfg.style = pick("style", ["PPTXGEN_IMAGE_STYLE"], cfg.style) or cfg.style
+    cfg.cache_dir = pick("cache_dir", ["PPTXGEN_IMAGE_CACHE"], cfg.cache_dir) or cfg.cache_dir
+    spec = cfg.spec
+
+    # mock 是本地占位图后端，不需要任何 base_url / model / key
+    if spec.kind == "mock":
+        cfg.base_url = config_base = spec.base_url
+        cfg.model = spec.default_model
+        cfg.size = cfg.size or spec.default_size
+        return cfg
+
+    cfg.api_key = pick("api_key", ["PPTXGEN_IMAGE_API_KEY"] + spec.key_envs)
+    cfg.base_url = pick("base_url", ["PPTXGEN_IMAGE_BASE_URL"], spec.base_url)
+    cfg.model = pick("model", ["PPTXGEN_IMAGE_MODEL"], spec.default_model)
+    cfg.size = pick("size", ["PPTXGEN_IMAGE_SIZE"], spec.default_size)
+
+    # 兜底：任何来源的占位符都不能当成真配置
+    for fieldname in ("base_url", "model", "api_key"):
+        if _is_placeholder(getattr(cfg, fieldname)):
+            setattr(cfg, fieldname, None)
+    if cfg.base_url is None and cfg.model is None:
+        srcs = getattr(load_config, "sources", None) or []
+        if srcs:
+            where = "  检查过的配置文件：\n" + "".join(f"    - {x}\n" for x in srcs)
+        else:
+            where = ("  还没有配置文件。建议创建全局配置（在任何项目下都生效）：\n"
+                     f"    mkdir -p {os.path.dirname(CONFIG_PATHS[1])}\n"
+                     f"    cp <引擎目录>/.pptxgen.yaml {CONFIG_PATHS[1]}\n")
+        raise ImageGenError(
+            "还没有配置图像模型。\n"
+            + where
+            + "  需要填的三项：base_url / model / api_key\n"
+            + "  也可以用环境变量：PPTXGEN_IMAGE_BASE_URL / PPTXGEN_IMAGE_MODEL / PPTXGEN_IMAGE_API_KEY\n"
+            + "  想先看版式效果可以加 --backend mock（本地占位图，不联网不花钱）。"
+        )
+    if not cfg.base_url:
+        raise ImageGenError(
+            f"后端 {cfg.backend} 没有配置 base_url。\n"
+            "  请设置 PPTXGEN_IMAGE_BASE_URL，或在 .pptxgen.yaml 里写 images.base_url"
+        )
+    if not cfg.model:
+        raise ImageGenError(
+            f"后端 {cfg.backend} 没有配置模型名。\n"
+            "  请设置 PPTXGEN_IMAGE_MODEL，或在 .pptxgen.yaml 里写 images.model"
+        )
+    return cfg
+
+
+def write_config_template(path: str, backend: str = "openai-compatible") -> str:
+    os.makedirs(os.path.dirname(os.path.abspath(path)) or ".", exist_ok=True)
+    content = f"""\
+# pptxgen 配图生成配置
+# 环境变量优先级高于本文件；也可以把本文件放在 ~/.pptxgen/config.yaml
+images:
+  backend: {backend}
+  base_url: https://your-relay.example.com/v1
+  model: your-image-model-name
+  api_key: sk-xxxxxxxx
+  size: "1024x1024"
+  cache_dir: out/images
+  style: >
+    {DEFAULT_STYLE}
+"""
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(content)
+    return path
+
+
+# --------------------------------------------------------------------------
+# 缓存
+# --------------------------------------------------------------------------
+def cache_key(prompt: str, style: str, model: str, size: str, backend: str) -> str:
+    raw = "\u0000".join([backend, model, size, style, prompt])
+    return hashlib.sha1(raw.encode("utf-8")).hexdigest()[:16]
+
+
+def cache_path(cache_dir: str, key: str) -> str:
+    return os.path.join(cache_dir, f"{key}.png")
+
+
+# --------------------------------------------------------------------------
+# 生成器
+# --------------------------------------------------------------------------
+class ImageGenerator:
+    def __init__(self, config: ImageConfig, *, verbose: bool = True):
+        self.cfg = config
+        self.verbose = verbose
+
+    # ---- 对外接口 ----------------------------------------------------
+    def key_for(self, prompt: str) -> str:
+        return cache_key(prompt, self.cfg.style, self.cfg.model or "", self.cfg.size or "",
+                         self.cfg.backend)
+
+    def lookup(self, prompt: str) -> Optional[str]:
+        p = cache_path(self.cfg.cache_dir, self.key_for(prompt))
+        return p if os.path.exists(p) and os.path.getsize(p) > 0 else None
+
+    def generate(self, prompt: str, *, force: bool = False) -> Tuple[str, bool]:
+        """返回 (图片路径, 是否命中缓存)。"""
+        key = self.key_for(prompt)
+        out = cache_path(self.cfg.cache_dir, key)
+        if not force and os.path.exists(out) and os.path.getsize(out) > 0:
+            return out, True
+        if self.cfg.spec.kind == "mock":
+            os.makedirs(self.cfg.cache_dir, exist_ok=True)
+            blob = _mock_image(prompt, self.cfg.size or "1024x1024")
+            tmp = out + ".part"
+            with open(tmp, "wb") as f:
+                f.write(blob)
+            os.replace(tmp, out)
+            return out, False
+        if not self.cfg.api_key:
+            raise ImageGenError(
+                f"后端 {self.cfg.backend} 缺少 API key。\n"
+                f"  请设置 {' 或 '.join(self.cfg.spec.key_envs[:2])}，"
+                "或运行 `pptxgen images --init-config` 生成配置文件。"
+            )
+        os.makedirs(self.cfg.cache_dir, exist_ok=True)
+        full = self._compose(prompt)
+        blob = self._request(full, prompt)
+        tmp = out + ".part"
+        with open(tmp, "wb") as f:
+            f.write(blob)
+        os.replace(tmp, out)
+        return out, False
+
+    def _compose(self, prompt: str) -> str:
+        style = (self.cfg.style or "").strip()
+        return f"{prompt.strip()}。{style}" if style else prompt.strip()
+
+    # ---- HTTP --------------------------------------------------------
+    def _request(self, full_prompt: str, raw_prompt: str) -> bytes:
+        kind = self.cfg.spec.kind
+        last: Optional[Exception] = None
+        for attempt in range(self.cfg.retries + 1):
+            try:
+                if kind == "gemini":
+                    return self._gemini(full_prompt)
+                if kind == "dashscope":
+                    return self._dashscope(full_prompt)
+                return self._openai(full_prompt)
+            except Exception as exc:      # 网络抖动可重试
+                last = exc
+                if attempt < self.cfg.retries:
+                    time.sleep(2 * (attempt + 1))
+                    continue
+        raise ImageGenError(f"生成失败：{last}")
+
+    def _openai(self, prompt: str) -> bytes:
+        url = self.cfg.base_url.rstrip("/") + "/images/generations"
+        body = {"model": self.cfg.model, "prompt": prompt, "n": 1}
+        if self.cfg.size:
+            body["size"] = self.cfg.size
+        data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(url, data=data, method="POST")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("Authorization", f"Bearer {self.cfg.api_key}")
+        payload = _post_json(req, self.cfg.timeout)
+        return _extract_image(payload, self.cfg.timeout)
+
+    def _gemini(self, prompt: str) -> bytes:
+        url = (f"{self.cfg.base_url.rstrip('/')}/models/{self.cfg.model}:generateContent"
+               f"?key={self.cfg.api_key}")
+        body = {"contents": [{"parts": [{"text": prompt}]}]}
+        req = urllib.request.Request(url, data=json.dumps(body).encode("utf-8"), method="POST")
+        req.add_header("Content-Type", "application/json")
+        payload = _post_json(req, self.cfg.timeout)
+        for cand in payload.get("candidates", []):
+            for part in cand.get("content", {}).get("parts", []):
+                inline = part.get("inlineData") or part.get("inline_data")
+                if inline and inline.get("data"):
+                    return base64.b64decode(inline["data"])
+        raise ImageGenError(f"Gemini 返回里没有图片：{json.dumps(payload)[:300]}")
+
+    def _dashscope(self, prompt: str) -> bytes:
+        """百炼/通义万相：异步提交 + 轮询。"""
+        url = self.cfg.base_url.rstrip("/") + "/services/aigc/text2image/image-synthesis"
+        body = {
+            "model": self.cfg.model,
+            "input": {"prompt": prompt},
+            "parameters": {"n": 1, "size": (self.cfg.size or "1024*1024").replace("x", "*")},
+        }
+        req = urllib.request.Request(url, data=json.dumps(body).encode("utf-8"), method="POST")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("Authorization", f"Bearer {self.cfg.api_key}")
+        req.add_header("X-DashScope-Async", "enable")
+        payload = _post_json(req, self.cfg.timeout)
+        task = (payload.get("output") or {}).get("task_id")
+        if not task:
+            raise ImageGenError(f"DashScope 未返回 task_id：{json.dumps(payload)[:300]}")
+        deadline = time.time() + self.cfg.timeout
+        while time.time() < deadline:
+            time.sleep(3)
+            q = urllib.request.Request(
+                f"{self.cfg.base_url.rstrip('/')}/tasks/{task}")
+            q.add_header("Authorization", f"Bearer {self.cfg.api_key}")
+            st = _post_json(q, self.cfg.timeout, method="GET")
+            out = st.get("output") or {}
+            if out.get("task_status") == "SUCCEEDED":
+                results = out.get("results") or []
+                if results and results[0].get("url"):
+                    return _download(results[0]["url"], self.cfg.timeout)
+                if results and results[0].get("b64_image"):
+                    return base64.b64decode(results[0]["b64_image"])
+                raise ImageGenError("DashScope 成功但没返回图片")
+            if out.get("task_status") == "FAILED":
+                raise ImageGenError(f"DashScope 任务失败：{out.get('message')}")
+        raise ImageGenError("DashScope 轮询超时")
+
+
+def _mock_image(prompt: str, size: str) -> bytes:
+    """生成一张本地占位图：柔和渐变 + 简单几何图形，用来预览版面效果。"""
+    import io
+    import random
+
+    from PIL import Image, ImageDraw
+
+    try:
+        w, h = (int(x) for x in size.lower().replace("*", "x").split("x"))
+    except Exception:
+        w, h = 1024, 1024
+    seed = int(hashlib.sha1(prompt.encode("utf-8")).hexdigest()[:8], 16)
+    rnd = random.Random(seed)
+    hue = rnd.random()
+
+    def hsl(t, s_=0.55, l_=0.80):
+        import colorsys
+
+        r, g, b = colorsys.hls_to_rgb(t % 1.0, l_, s_)
+        return int(r * 255), int(g * 255), int(b * 255)
+
+    img = Image.new("RGB", (w, h), hsl(hue, 0.35, 0.95))
+    d = ImageDraw.Draw(img, "RGBA")
+    for i in range(h):
+        t = i / max(h - 1, 1)
+        c = hsl(hue + 0.06 * t, 0.40, 0.97 - 0.13 * t)
+        d.line([(0, i), (w, i)], fill=c)
+    cx, cy = int(w * 0.5), int(h * 0.44)
+    r = int(min(w, h) * 0.21)
+    d.ellipse([cx - r, cy - r, cx + r, cy + r], fill=hsl(hue + 0.12, 0.62, 0.66))
+    d.ellipse([cx - int(r * 1.9), cy + int(r * 0.55), cx + int(r * 1.9), cy + int(r * 1.35)],
+              fill=hsl(hue + 0.30, 0.45, 0.86, ))
+    d.ellipse([cx - int(r * 2.5), cy + int(r * 0.95), cx + int(r * 2.5), cy + int(r * 1.8)],
+              fill=hsl(hue + 0.42, 0.40, 0.92))
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    return buf.getvalue()
+
+
+def normalize_dir(path: str, base: str) -> str:
+    """把相对 cache_dir 解析到 base 下并规范化（去掉 .. 段）。"""
+    if not path:
+        path = "out/images"
+    if not os.path.isabs(path):
+        path = os.path.join(base, path)
+    return os.path.normpath(path)
+
+
+# --------------------------------------------------------------------------
+# HTTP 工具
+# --------------------------------------------------------------------------
+def _ssl_ctx():
+    try:
+        import certifi  # type: ignore
+
+        return ssl.create_default_context(cafile=certifi.where())
+    except Exception:
+        return ssl.create_default_context()
+
+
+def _post_json(req, timeout: int, method: Optional[str] = None) -> dict:
+    if method:
+        req.method = method
+    try:
+        with urllib.request.urlopen(req, timeout=timeout, context=_ssl_ctx()) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", "ignore")[:400]
+        raise ImageGenError(f"HTTP {exc.code}：{detail}") from exc
+    except urllib.error.URLError as exc:
+        raise ImageGenError(f"网络错误：{exc.reason}") from exc
+
+
+def _download(url: str, timeout: int) -> bytes:
+    with urllib.request.urlopen(url, timeout=timeout, context=_ssl_ctx()) as resp:
+        return resp.read()
+
+
+def _extract_image(payload: dict, timeout: int) -> bytes:
+    data = payload.get("data")
+    if isinstance(data, list) and data:
+        item = data[0]
+        if item.get("b64_json"):
+            return base64.b64decode(item["b64_json"])
+        if item.get("url"):
+            return _download(item["url"], timeout)
+    if isinstance(data, dict) and data.get("url"):
+        return _download(data["url"], timeout)
+    raise ImageGenError(f"返回里没有图片数据：{json.dumps(payload)[:300]}")
+
+
+# --------------------------------------------------------------------------
+# 与课件规格对接
+# --------------------------------------------------------------------------
+def collect_jobs(deck: dict, cfg: ImageConfig) -> List[dict]:
+    """列出这份课件里所有待生成的配图。"""
+    jobs = []
+    for i, spec in enumerate(deck.get("slides", []), start=1):
+        prompt = (spec.get("image_prompt") or "").strip()
+        if not prompt:
+            continue
+        key = cache_key(prompt, cfg.style, cfg.model or "", cfg.size or "", cfg.backend)
+        jobs.append({
+            "index": i,
+            "type": spec.get("type"),
+            "title": spec.get("title", ""),
+            "prompt": prompt,
+            "key": key,
+            "path": cache_path(cfg.cache_dir, key),
+            "cached": os.path.exists(cache_path(cfg.cache_dir, key)),
+        })
+    return jobs
+
+
+MANIFEST_NAME = "manifest.json"
+
+
+def manifest_path(cache_dir: str) -> str:
+    return os.path.join(cache_dir, MANIFEST_NAME)
+
+
+def read_manifest(cache_dir: str) -> Dict[str, str]:
+    """prompt -> 图片路径。渲染阶段靠它把 image_prompt 变成真实图片。"""
+    try:
+        with open(manifest_path(cache_dir), "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return {k: v for k, v in (data.get("images") or {}).items() if os.path.exists(v)}
+    except Exception:
+        return {}
+
+
+def _write_manifest(cache_dir: str, mapping: Dict[str, str]) -> None:
+    os.makedirs(cache_dir, exist_ok=True)
+    with open(manifest_path(cache_dir), "w", encoding="utf-8") as f:
+        json.dump({"images": mapping}, f, ensure_ascii=False, indent=2)
+
+
+def generate_for_deck(deck: dict, cfg: ImageConfig, *, force: bool = False,
+                      limit: Optional[int] = None, verbose: bool = True) -> dict:
+    """为整份课件生成配图，返回统计。"""
+    gen = ImageGenerator(cfg, verbose=verbose)
+    jobs = collect_jobs(deck, cfg)
+    if limit:
+        jobs = jobs[:limit]
+    stats = {"total": len(jobs), "done": 0, "cached": 0, "failed": []}
+    mapping = read_manifest(cfg.cache_dir)
+    for j in jobs:
+        try:
+            path, hit = gen.generate(j["prompt"], force=force)
+            mapping[j["prompt"]] = os.path.abspath(path)
+            if hit:
+                stats["cached"] += 1
+                if verbose:
+                    print(f"  [缓存] P{j['index']:>2} {j['title'][:26]}")
+            else:
+                stats["done"] += 1
+                if verbose:
+                    print(f"  [生成] P{j['index']:>2} {j['title'][:26]}  -> {os.path.basename(path)}")
+        except Exception as exc:
+            stats["failed"].append((j["index"], str(exc)))
+            if verbose:
+                print(f"  [失败] P{j['index']:>2} {j['title'][:26]}  {exc}", file=sys.stderr)
+    _write_manifest(cfg.cache_dir, mapping)
+    return stats