astrbot_plugin_imagestudio/backend/services/generation_reference_service.py

480 行
18 KiB
Python

"""Resolve generation reference images into provider-ready inputs."""
from __future__ import annotations
import base64
import binascii
import re
from typing import Any, Protocol
from urllib.parse import urlsplit
from backend.dto.common import ApiError, ErrorCode
from backend.services.image_service import ImageService
from backend.services.material_catalog_resolver import is_trusted_advanced_metadata
from core.storage import VfsStorage
MAX_REFERENCE_IMAGE_BYTES = 25 * 1024 * 1024
MAX_REFERENCE_IMAGE_TOTAL_BYTES = 50 * 1024 * 1024
MAX_REFERENCE_IMAGES = 16
_SUPPORTED_IMAGE_MIMES = {"image/png", "image/jpeg", "image/gif", "image/webp"}
_DATA_IMAGE_RE = re.compile(r"^data:([^;,]+)(?:;[^,]*)?;base64,(.*)$", re.IGNORECASE | re.DOTALL)
class MaterialResolver(Protocol):
def get_material(self, material_id: str) -> Any | None: ...
class GenerationReferenceService:
def __init__(
self,
image_service: ImageService,
storage: VfsStorage,
material_resolver: MaterialResolver | None = None,
):
self.image_service = image_service
self.storage = storage
self.material_resolver = material_resolver
def resolve(self, workflow_id: str, payload: dict[str, Any]) -> tuple[str, ...]:
resolved: list[str] = []
seen: set[str] = set()
image_cache: dict[str, Any] = {}
storage_cache: dict[str, tuple[str, int]] = {}
total_bytes = 0
for value, source, force_image_id in _reference_candidates(payload):
prepared, canonical_key, byte_count = self._resolve_candidate(
workflow_id,
value,
source=source,
force_image_id=force_image_id,
image_cache=image_cache,
storage_cache=storage_cache,
)
total_bytes = _append_reference(
resolved,
seen,
prepared,
canonical_key,
byte_count,
total_bytes,
source,
)
if self.material_resolver is not None:
for material_id, source in _material_reference_candidates(payload):
for prepared, canonical_key, byte_count in self._resolve_material_references(
material_id,
source=source,
storage_cache=storage_cache,
):
total_bytes = _append_reference(
resolved,
seen,
prepared,
canonical_key,
byte_count,
total_bytes,
source,
)
return tuple(resolved)
def _resolve_material_references(
self,
material_id: str,
*,
source: str,
storage_cache: dict[str, tuple[str, int]],
) -> list[tuple[str, str, int]]:
material = self.material_resolver.get_material(material_id) if self.material_resolver else None
if material is None:
raise ApiError(
ErrorCode.RESOURCE_NOT_FOUND,
"reference material does not exist",
{"material_id": material_id, "source": source},
)
if str(material.recognition_status or "").strip() != "confirmed":
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"reference material is not confirmed",
{
"material_id": material_id,
"recognition_status": material.recognition_status,
"source": source,
},
)
metadata = material.metadata if isinstance(getattr(material, "metadata", None), dict) else {}
if is_trusted_advanced_metadata(metadata) and isinstance(metadata.get("style_set"), dict):
# Quick/direct generation consumes the verified style capsule as
# text. Source images are deliberately withheld to avoid leaking
# sample characters, clothing, composition or scenery.
return []
image_uri = _optional_text(material.image_uri)
if not image_uri:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"confirmed reference material has no image",
{"material_id": material_id, "source": source},
)
# Detailed persisted rounds expand trusted style representatives only
# after the concrete route capabilities are known.
return [self._prepare_uri(image_uri, source=source, storage_cache=storage_cache)]
def _resolve_candidate(
self,
workflow_id: str,
value: Any,
*,
source: str,
force_image_id: bool,
image_cache: dict[str, Any],
storage_cache: dict[str, tuple[str, int]],
) -> tuple[str, str, int]:
if isinstance(value, dict):
image_id = _optional_text(value.get("image_id"))
if image_id:
return self._resolve_image_id(
workflow_id,
image_id,
source=source,
image_cache=image_cache,
storage_cache=storage_cache,
)
for key in ("image_uri", "url", "data_url", "input_image"):
reference = _optional_text(value.get(key))
if reference:
return self._prepare_uri(reference, source=source, storage_cache=storage_cache)
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"reference image object must include image_id or image_uri",
{"source": source},
)
reference = _optional_text(value)
if not reference:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"reference image cannot be empty",
{"source": source},
)
if force_image_id or not _is_reference_uri(reference):
return self._resolve_image_id(
workflow_id,
reference,
source=source,
image_cache=image_cache,
storage_cache=storage_cache,
)
return self._prepare_uri(reference, source=source, storage_cache=storage_cache)
def _resolve_image_id(
self,
workflow_id: str,
image_id: str,
*,
source: str,
image_cache: dict[str, Any],
storage_cache: dict[str, tuple[str, int]],
) -> tuple[str, str, int]:
image = image_cache.get(image_id)
if image is None:
try:
image = self.image_service.get_image(image_id)
except ApiError as exc:
if exc.error_code != ErrorCode.RESOURCE_NOT_FOUND:
raise
raise ApiError(
ErrorCode.RESOURCE_NOT_FOUND,
"reference image does not exist",
{"image_id": image_id, "source": source},
) from exc
image_cache[image_id] = image
if image.workflow_id != workflow_id:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"reference image does not belong to this workflow",
{
"image_id": image_id,
"workflow_id": workflow_id,
"image_workflow_id": image.workflow_id,
"source": source,
},
)
return self._prepare_uri(image.image_uri, source=source, storage_cache=storage_cache)
def _prepare_uri(
self,
reference: str,
*,
source: str,
storage_cache: dict[str, tuple[str, int]],
) -> tuple[str, str, int]:
if reference.startswith("storage://"):
cached = storage_cache.get(reference)
if cached is None:
try:
path = self.storage.ensure_file(reference)
size = path.stat().st_size
if size > MAX_REFERENCE_IMAGE_BYTES:
raise _image_too_large(reference, size, source)
body = path.read_bytes()
except ApiError as exc:
if exc.error_code != ErrorCode.MEDIA_NOT_FOUND:
raise
raise ApiError(
ErrorCode.MEDIA_NOT_FOUND,
"reference image file does not exist",
{"uri": reference, "source": source},
) from exc
except OSError as exc:
raise ApiError(
ErrorCode.MEDIA_NOT_FOUND,
"reference image file could not be read",
{"uri": reference, "source": source},
) from exc
if len(body) > MAX_REFERENCE_IMAGE_BYTES:
raise _image_too_large(reference, len(body), source)
mime = _detect_image_mime(body)
if mime is None:
raise ApiError(
ErrorCode.UNSUPPORTED_FILE_TYPE,
"reference image is not a supported PNG, JPEG, GIF, or WebP image",
{"uri": reference, "source": source},
)
cached = (f"data:{mime};base64,{base64.b64encode(body).decode('ascii')}", len(body))
storage_cache[reference] = cached
return cached[0], f"storage:{reference}", cached[1]
if reference.lower().startswith("data:"):
byte_count = _validate_data_image_url(reference, source=source)
return reference, f"data:{reference}", byte_count
parsed = urlsplit(reference)
if parsed.scheme.lower() in {"http", "https"} and parsed.hostname:
return reference, f"url:{reference}", 0
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"reference image must be an image ID, storage URI, HTTP(S) URL, or image data URL",
{"reference": reference, "source": source},
)
def _reference_candidates(payload: dict[str, Any]) -> list[tuple[Any, str, bool]]:
candidates: list[tuple[Any, str, bool]] = []
for key in ("input_images", "image"):
for index, value in enumerate(_ordered_values(payload.get(key))):
candidates.append((value, f"{key}[{index}]", False))
dependency_context = payload.get("dependency_context")
if not isinstance(dependency_context, dict):
dependency_context = {}
for index, value in enumerate(_ordered_values(dependency_context.get("selected_image_ids"))):
candidates.append((value, f"dependency_context.selected_image_ids[{index}]", True))
metadata = payload.get("metadata") if isinstance(payload.get("metadata"), dict) else {}
for prefix, value in (
("selected_draft_image_ids", payload.get("selected_draft_image_ids")),
("metadata.selected_draft_image_ids", metadata.get("selected_draft_image_ids")),
("dependency_context.selected_draft_image_ids", dependency_context.get("selected_draft_image_ids")),
):
for index, image_id in enumerate(_ordered_values(value)):
candidates.append((image_id, f"{prefix}[{index}]", True))
injection_template = (
dependency_context.get("injection_template")
if isinstance(dependency_context.get("injection_template"), dict)
else {}
)
for index, image_id in enumerate(_ordered_values(injection_template.get("selected_draft_image_ids"))):
candidates.append(
(
image_id,
f"dependency_context.injection_template.selected_draft_image_ids[{index}]",
True,
)
)
for prefix, value in (
("stage_inputs", payload.get("stage_inputs")),
("metadata.stage_inputs", metadata.get("stage_inputs")),
("dependency_context.stage_inputs", dependency_context.get("stage_inputs")),
("dependency_context.injection_template.stage_inputs", injection_template.get("stage_inputs")),
):
for index, reference in enumerate(_stage_input_references(value)):
candidates.append((reference, f"{prefix}[{index}]", False))
return candidates
def _material_reference_candidates(payload: dict[str, Any]) -> list[tuple[str, str]]:
dependency_context = payload.get("dependency_context")
if not isinstance(dependency_context, dict):
return []
bindings = dependency_context.get("material_bindings")
if not isinstance(bindings, dict):
return []
candidates: list[tuple[str, str]] = []
generation_params = bindings.get("generation_params")
if isinstance(generation_params, dict):
for index, material_id in enumerate(_ordered_values(generation_params.get("reference_material_ids"))):
text = _optional_text(material_id)
if text:
candidates.append(
(text, f"dependency_context.material_bindings.generation_params.reference_material_ids[{index}]")
)
active_bindings = bindings.get("active_bindings")
if isinstance(active_bindings, list):
for index, binding in enumerate(active_bindings):
if not isinstance(binding, dict):
continue
material = binding.get("material") if isinstance(binding.get("material"), dict) else {}
material_id = _optional_text(material.get("material_id") or binding.get("material_id"))
if material_id:
candidates.append(
(material_id, f"dependency_context.material_bindings.active_bindings[{index}].material_id")
)
result: list[tuple[str, str]] = []
seen: set[str] = set()
for material_id, source in candidates:
if material_id not in seen:
result.append((material_id, source))
seen.add(material_id)
return result
def _append_reference(
resolved: list[str],
seen: set[str],
prepared: str,
canonical_key: str,
byte_count: int,
total_bytes: int,
source: str,
) -> int:
if canonical_key in seen:
return total_bytes
if len(resolved) >= MAX_REFERENCE_IMAGES:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"too many reference images",
{"max_reference_images": MAX_REFERENCE_IMAGES, "source": source},
)
if total_bytes + byte_count > MAX_REFERENCE_IMAGE_TOTAL_BYTES:
raise ApiError(
ErrorCode.UPLOAD_TOO_LARGE,
"reference images exceed the total size limit",
{"max_total_bytes": MAX_REFERENCE_IMAGE_TOTAL_BYTES, "source": source},
)
resolved.append(prepared)
seen.add(canonical_key)
return total_bytes + byte_count
def _ordered_values(value: Any) -> list[Any]:
values = list(value) if isinstance(value, (list, tuple)) else ([] if value is None else [value])
return [item for item in values if not isinstance(item, str) or item.strip()]
def _stage_input_references(value: Any) -> list[Any]:
if value is None:
return []
if isinstance(value, str):
return [value] if value.strip() else []
if isinstance(value, (list, tuple)):
return [reference for item in value for reference in _stage_input_references(item)]
if not isinstance(value, dict):
return []
if any(_optional_text(value.get(key)) for key in ("image_id", "image_uri", "url", "data_url")):
return [value]
return [
reference
for item in value.values()
if isinstance(item, (dict, list, tuple))
for reference in _stage_input_references(item)
]
def _validate_data_image_url(value: str, *, source: str) -> int:
match = _DATA_IMAGE_RE.fullmatch(value)
if match is None:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"reference data URL must contain a base64-encoded image",
{"source": source},
)
declared_mime = match.group(1).strip().lower()
if declared_mime == "image/jpg":
declared_mime = "image/jpeg"
if declared_mime not in _SUPPORTED_IMAGE_MIMES:
raise ApiError(
ErrorCode.UNSUPPORTED_FILE_TYPE,
"reference data URL uses an unsupported image type",
{"mime": declared_mime, "source": source},
)
encoded = re.sub(r"\s+", "", match.group(2))
if len(encoded) > ((MAX_REFERENCE_IMAGE_BYTES + 2) // 3) * 4:
raise ApiError(
ErrorCode.UPLOAD_TOO_LARGE,
"reference data URL exceeds the size limit",
{"max_bytes": MAX_REFERENCE_IMAGE_BYTES, "source": source},
)
try:
body = base64.b64decode(encoded, validate=True)
except (binascii.Error, ValueError) as exc:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"reference data URL contains invalid base64",
{"source": source},
) from exc
if len(body) > MAX_REFERENCE_IMAGE_BYTES:
raise ApiError(
ErrorCode.UPLOAD_TOO_LARGE,
"reference data URL exceeds the size limit",
{"bytes": len(body), "max_bytes": MAX_REFERENCE_IMAGE_BYTES, "source": source},
)
detected_mime = _detect_image_mime(body)
if detected_mime is None:
raise ApiError(
ErrorCode.UNSUPPORTED_FILE_TYPE,
"reference data URL does not contain a supported image",
{"source": source},
)
if detected_mime != declared_mime:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"reference data URL MIME type does not match its image payload",
{"declared_mime": declared_mime, "detected_mime": detected_mime, "source": source},
)
return len(body)
def _detect_image_mime(body: bytes) -> str | None:
if body.startswith(b"\x89PNG\r\n\x1a\n"):
return "image/png"
if body.startswith(b"\xff\xd8\xff"):
return "image/jpeg"
if body.startswith((b"GIF87a", b"GIF89a")):
return "image/gif"
if len(body) >= 12 and body.startswith(b"RIFF") and body[8:12] == b"WEBP":
return "image/webp"
return None
def _image_too_large(uri: str, size: int, source: str) -> ApiError:
return ApiError(
ErrorCode.UPLOAD_TOO_LARGE,
"reference image exceeds the size limit",
{"uri": uri, "bytes": size, "max_bytes": MAX_REFERENCE_IMAGE_BYTES, "source": source},
)
def _is_reference_uri(value: str) -> bool:
return value.lower().startswith(("storage://", "data:", "http://", "https://"))
def _optional_text(value: Any) -> str | None:
if value is None:
return None
text = str(value).strip()
return text or None