astrbot_plugin_imagestudio/backend/services/advanced_material_service.py

1852 行
82 KiB
Python

"""Verified advanced-material import and validation workflow.
Advanced materials intentionally use their own tables and VFS root. The
source image is recognized first, then the recognized text (and only that
text) is rendered once so a human can judge whether the description is
faithful enough to seal into the high-priority material catalog.
"""
from __future__ import annotations
from dataclasses import replace
from pathlib import Path, PurePosixPath
from typing import Any
from uuid import uuid4
from backend.dto.common import ApiError, ErrorCode
from backend.dto.job_dto import GenerationTask
from backend.dto.material_dto import Material
from backend.dto.workflow_dto import WorkflowNode
from backend.services.event_stream_service import get_default_event_bus
from backend.services.cost_guard_service import CostGuardService
from backend.services.cost_service import CostService
from backend.services.material_normalization_service import (
MaterialNormalizationError,
MaterialNormalizationService,
)
from backend.services.material_service import (
MAX_UPLOAD_BYTES,
_decode_upload_data_url,
_display_name_from_filename,
_normalize_upload_content_type,
_normalize_upload_filename,
_normalize_upload_metadata,
_normalize_upload_size,
_recognition_metadata,
_storage_image_data_url,
_suffix,
_vision_provider_error,
)
from backend.services.model_provider_bootstrap import (
sync_generation_provider_from_config,
sync_vision_provider_from_config,
)
from backend.services.model_provider_runtime import ModelProviderRuntime
from backend.services.model_provider_service import ModelProviderService
from backend.services.queue_service import QueueService
from backend.services.prompt_governance_service import (
GenerationFailureClassifier,
GenerationRouteService,
PromptModerationDecision,
PromptModerationService,
)
from backend.services.worker_service import WorkerTaskUpdate
from backend.services.advanced_style_set_service import AdvancedStyleSetService
from core.audit_service import AuditService
from core.astrbot_provider_bridge import astrbot_structured_text_callable
from core.identity import RequestContext
from core.image_formats import detect_image_format
from core.storage import VfsStorage
from database.db_helper import Database, load_config_file_payload, load_config_payload, load_database_settings
from database.repositories.advanced_material_repository import AdvancedMaterialRepository
from database.repositories.job_repository import JobRepository
from database.repositories.material_repository import MaterialRepository
from database.repositories.model_provider_repository import ModelProviderRepository
from engines.image_provider import ImageProviderError
from engines.single_flow import SingleFlowEngine
from engines.vision_provider import VisionProviderError, VisionRecognitionRequest
from core.text_utils import optional_text as _optional_text
IMPORT_ACTIVE_STATUSES = {"recognition_queued", "recognizing", "validation_queued", "validating"}
IMPORT_REVIEW_STATUSES = {"awaiting_review", "adjustment_required"}
ATTEMPT_ACTIVE_STATUSES = {"queued", "running"}
ADVANCED_MATERIAL_PRIORITY = 100
DEFAULT_VALIDATION_SEED = 240719
class AdvancedMaterialTaskCancelled(RuntimeError):
"""Raised when a late provider result no longer owns its import."""
class AdvancedMaterialService:
def __init__(
self,
repository: AdvancedMaterialRepository,
material_repository: MaterialRepository,
queue_service: QueueService,
audit_service: AuditService,
model_provider_service: ModelProviderService,
model_provider_runtime: ModelProviderRuntime,
*,
config: dict[str, Any] | None = None,
storage: VfsStorage | None = None,
normalization_service: MaterialNormalizationService | None = None,
single_flow_engine: SingleFlowEngine | None = None,
prompt_moderation_service: PromptModerationService | None = None,
generation_route_service: GenerationRouteService | None = None,
cost_guard_service: CostGuardService | None = None,
failure_classifier: GenerationFailureClassifier | None = None,
):
self.repository = repository
self.material_repository = material_repository
self.queue_service = queue_service
self.audit_service = audit_service
self.model_provider_service = model_provider_service
self.model_provider_runtime = model_provider_runtime
self.config = config or {}
self.storage = storage or VfsStorage()
self.normalization_service = normalization_service or MaterialNormalizationService()
self.prompt_moderation_service = prompt_moderation_service
self.generation_route_service = generation_route_service
self.cost_guard_service = cost_guard_service
self.failure_classifier = failure_classifier or GenerationFailureClassifier()
self.single_flow_engine = single_flow_engine or SingleFlowEngine(
storage=self.storage,
image_provider_factory=self.model_provider_runtime.image_provider_for_route,
allow_mock_fallback=False,
)
self.style_sets = AdvancedStyleSetService(self)
def upload(self, payload: dict[str, Any], ctx: RequestContext) -> dict[str, Any]:
import_id = f"advimp_{uuid4().hex}"
filename = _normalize_upload_filename(payload.get("filename"))
content_type = _normalize_upload_content_type(payload.get("content_type"))
declared_size = _normalize_upload_size(payload)
upload_metadata = _normalize_upload_metadata(payload.get("metadata"))
source_uri, detected_type, size_bytes, original_filename = self._persist_source(
import_id=import_id,
image_data_url=str(payload.get("image_data_url") or "").strip(),
image_uri=str(payload.get("image_uri") or "").strip(),
filename=filename,
declared_content_type=content_type,
declared_size=declared_size,
)
display_name = str(
payload.get("display_name")
or _display_name_from_filename(original_filename)
or "进阶素材"
).strip()
category_id = _optional_text(payload.get("category_id"))
if category_id and self.material_repository.get_category(category_id) is None:
self._remove_uri(source_uri)
raise ApiError(
ErrorCode.RESOURCE_NOT_FOUND,
"material category not found",
{"category_id": category_id},
)
recognition_route = _optional_text(payload.get("recognition_model_route")) or self._recognition_route()
generation_route = _optional_text(payload.get("generation_model_route")) or self._generation_route()
try:
record = self.repository.create_import(
{
"import_id": import_id,
"category_id": category_id,
"display_name": display_name,
"source_image_uri": source_uri,
"source_thumbnail_uri": source_uri,
"status": "recognition_queued",
"recognition_model_route": recognition_route,
"prompt_revision": 0,
"created_by": ctx.actor_id,
"metadata": {
"upload": {
**upload_metadata,
"filename": original_filename,
"content_type": detected_type,
"size_bytes": size_bytes,
"source": str(payload.get("upload_source") or "file"),
"storage_root": "advanced_materials",
},
"generation_model_route": generation_route,
"governance_context": _governance_context(self.config, ctx),
"material_tier": "advanced_pending",
},
}
)
except Exception:
self._remove_uri(source_uri)
raise
try:
task = self._queue_recognition(record, ctx)
except Exception as exc:
self.repository.update_import(
record.import_id,
{"status": "recognition_failed", "error": _safe_failure(exc)},
)
raise
self.audit_service.record(
ctx=ctx,
action="upload_advanced_material",
target_type="advanced_material_import",
target_id=record.import_id,
after_snapshot=record.to_dict(),
metadata={"task_id": task.task_id},
)
return {"import": self.repository.get_import(record.import_id).to_dict(), "task": task.to_dict()}
def upload_style_set(self, payload: dict[str, Any], ctx: RequestContext) -> dict[str, Any]:
return self.style_sets.upload(payload, ctx)
def list_imports(
self,
*,
status: str | None = None,
page: int = 1,
page_size: int = 30,
) -> dict[str, Any]:
items, total = self.repository.list_imports(
status=status,
page=max(int(page or 1), 1),
page_size=min(max(int(page_size or 30), 1), 100),
)
reconciled = [self._reconcile_import_task(item) for item in items]
return {
"items": [item.to_dict() for item in reconciled],
"total": total,
"page": max(int(page or 1), 1),
"page_size": min(max(int(page_size or 30), 1), 100),
}
def get_import(self, import_id: str) -> dict[str, Any]:
record = self._reconcile_import_task(self._require_import(import_id))
attempts = self.repository.list_attempts(import_id)
is_style_set = self.style_sets.is_style_set(record)
style_detail = self.style_sets.detail(record) if is_style_set else {}
attempt_payloads = [
{
**attempt.to_dict(),
**(
{
"validation_cases": [
case.to_dict()
for case in self.repository.list_style_validation_cases(attempt.attempt_id)
]
}
if is_style_set
else {}
),
}
for attempt in attempts
]
import_payload = {
**record.to_dict(),
**(
{
"style_set": True,
"sources": style_detail.get("sources", []),
"consensus": style_detail.get("consensus"),
"consensus_history": style_detail.get("consensus_history", []),
"validation_cases": style_detail.get("validation_cases", []),
}
if style_detail
else {}
),
}
return {
**style_detail,
"import": import_payload,
"attempts": attempt_payloads,
"accepted_material": (
self.repository.get_material(record.accepted_material_id).to_dict()
if record.accepted_material_id and self.repository.get_material(record.accepted_material_id)
else None
),
}
def retry_style_source(self, import_id: str, source_id: str, ctx: RequestContext) -> dict[str, Any]:
return self.style_sets.retry_source(import_id, source_id, ctx)
def exclude_style_source(
self,
import_id: str,
source_id: str,
excluded: bool,
ctx: RequestContext,
) -> dict[str, Any]:
return self.style_sets.exclude_source(import_id, source_id, excluded, ctx)
def create_style_consensus(
self,
import_id: str,
payload: dict[str, Any],
ctx: RequestContext,
) -> dict[str, Any]:
return self.style_sets.create_consensus(import_id, payload, ctx)
def retry_style_validation_case(self, import_id: str, case_id: str, ctx: RequestContext) -> dict[str, Any]:
return self.style_sets.retry_validation_case(import_id, case_id, ctx)
def list_attempts(self, import_id: str) -> list[dict[str, Any]]:
record = self._require_import(import_id)
is_style_set = self.style_sets.is_style_set(record)
return [
{
**attempt.to_dict(),
**(
{
"validation_cases": [
case.to_dict()
for case in self.repository.list_style_validation_cases(attempt.attempt_id)
]
}
if is_style_set
else {}
),
}
for attempt in self.repository.list_attempts(import_id)
]
def create_validation_attempt(
self,
import_id: str,
payload: dict[str, Any],
ctx: RequestContext,
) -> dict[str, Any]:
record = self._require_import(import_id)
if self.style_sets.is_style_set(record):
return self.style_sets.ensure_validation(record, payload, ctx)
record = self.repository.update_import(
import_id,
{"metadata": {**record.metadata, "governance_context": _governance_context(self.config, ctx)}},
) or record
adjustment = _optional_text(payload.get("adjustment_text"))
if adjustment:
record = self._apply_adjustment(record, adjustment, ctx)
attempt, task = self._queue_validation(record, ctx)
return {"import": self._require_import(import_id).to_dict(), "attempt": attempt.to_dict(), "task": task.to_dict()}
def reject_attempt(
self,
import_id: str,
attempt_id: str,
payload: dict[str, Any],
ctx: RequestContext,
) -> dict[str, Any]:
record = self._require_import(import_id)
attempt = self._require_attempt(import_id, attempt_id)
if self.style_sets.is_style_set(record):
return self.style_sets.reject_and_rebuild(record, attempt, payload, ctx)
if record.current_attempt_id != attempt.attempt_id or record.status != "awaiting_review" or attempt.status != "awaiting_review":
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"only the current completed verification attempt can be rejected",
{"import_id": import_id, "attempt_id": attempt_id, "status": attempt.status},
)
adjustment = _optional_text(payload.get("adjustment_text"))
if not adjustment:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"adjustment_text is required when the verification image is not faithful",
{"field": "adjustment_text"},
)
before = attempt.to_dict()
updated_attempt = self.repository.update_attempt(
attempt_id,
{
"status": "rejected",
"decision": "rejected",
"decision_notes": _optional_text(payload.get("decision_notes")) or adjustment,
"fidelity_score": _optional_score(payload.get("fidelity_score")),
"metadata": {**attempt.metadata, "rejected_by": ctx.actor_id},
},
)
self.repository.update_import(import_id, {"status": "adjustment_required"})
adjusted = self._apply_adjustment(self._require_import(import_id), adjustment, ctx)
next_attempt, task = self._queue_validation(adjusted, ctx)
self.audit_service.record(
ctx=ctx,
action="reject_advanced_material_attempt",
target_type="advanced_material_validation_attempt",
target_id=attempt_id,
before_snapshot=before,
after_snapshot=updated_attempt.to_dict(),
metadata={"next_attempt_id": next_attempt.attempt_id, "task_id": task.task_id},
)
return {
"import": self._require_import(import_id).to_dict(),
"attempt": updated_attempt.to_dict(),
"next_attempt": next_attempt.to_dict(),
"task": task.to_dict(),
}
def accept_attempt(
self,
import_id: str,
attempt_id: str,
payload: dict[str, Any],
ctx: RequestContext,
) -> dict[str, Any]:
record = self._require_import(import_id)
attempt = self._require_attempt(import_id, attempt_id)
if self.style_sets.is_style_set(record):
return self.style_sets.accept(record, attempt, payload, ctx)
if record.accepted_material_id:
existing = self.repository.get_material(record.accepted_material_id)
if existing is not None:
return {"import": record.to_dict(), "attempt": attempt.to_dict(), "material": existing.to_dict()}
if record.current_attempt_id != attempt_id or record.status != "awaiting_review" or attempt.status != "awaiting_review":
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"only the current completed verification attempt can be sealed",
{"import_id": import_id, "attempt_id": attempt_id, "status": attempt.status},
)
if not attempt.validation_image_uri:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"verification image is missing",
{"attempt_id": attempt_id},
)
material_id = f"advmat_{uuid4().hex}"
recognition = record.recognition_result if isinstance(record.recognition_result, dict) else {}
profile = recognition.get("normalized_asset_profile") if isinstance(recognition.get("normalized_asset_profile"), dict) else {}
capsules = recognition.get("generation_capsules") if isinstance(recognition.get("generation_capsules"), dict) else {}
fidelity_score = _optional_score(payload.get("fidelity_score"))
decision_notes = _optional_text(payload.get("decision_notes"))
attempt = self.repository.update_attempt(
attempt_id,
{"fidelity_score": fidelity_score, "decision_notes": decision_notes},
) or attempt
metadata = {
"library_kind": "advanced",
"priority_class": "advanced_verified",
"material_priority": ADVANCED_MATERIAL_PRIORITY,
"verification": {
"import_id": import_id,
"attempt_id": attempt_id,
"attempt_number": attempt.attempt_number,
"fidelity_score": fidelity_score,
"decision_notes": decision_notes,
"validation_image_uri": attempt.validation_image_uri,
"prompt_revision": record.prompt_revision,
},
"recognition": recognition.get("recognition") or {},
"raw_analysis": recognition.get("raw_analysis") or {},
"normalized_asset_profile": {**profile, "confirmed": True},
"generation_capsules": capsules,
"confirmed": True,
}
material = self.repository.accept_attempt(
import_id,
attempt_id,
{
"material_id": material_id,
"category_id": record.category_id,
"display_name": record.display_name,
"source_image_uri": record.source_image_uri,
"source_thumbnail_uri": record.source_thumbnail_uri,
"validation_image_uri": attempt.validation_image_uri,
"validation_thumbnail_uri": attempt.validation_thumbnail_uri,
"prompt": attempt.prompt or record.recognition_prompt,
"negative_prompt": attempt.negative_prompt or record.recognition_negative_prompt,
"tags": record.recognition_tags,
"priority": ADVANCED_MATERIAL_PRIORITY,
"status": "active",
"capsule": capsules,
"fidelity_score": fidelity_score,
"created_by": ctx.actor_id,
"decision_notes": decision_notes,
"metadata": metadata,
},
)
self.audit_service.record(
ctx=ctx,
action="seal_advanced_material",
target_type="advanced_material",
target_id=material.material_id,
before_snapshot={"import": record.to_dict(), "attempt": attempt.to_dict()},
after_snapshot=material.to_dict(),
)
return {
"import": self._require_import(import_id).to_dict(),
"attempt": self._require_attempt(import_id, attempt_id).to_dict(),
"material": material.to_dict(),
}
def retry_import(self, import_id: str, ctx: RequestContext) -> dict[str, Any]:
record = self._reconcile_import_task(self._require_import(import_id))
record = self.repository.update_import(
import_id,
{"metadata": {**record.metadata, "governance_context": _governance_context(self.config, ctx)}},
) or record
if self.style_sets.is_style_set(record):
if record.status == "style_consensus_failed":
return self.style_sets.create_consensus(import_id, {}, ctx)
if record.status in {"ready_for_validation", "validation_failed"}:
return self.style_sets.ensure_validation(record, {}, ctx)
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"retry the failed style source or validation case directly",
{"import_id": import_id, "status": record.status},
)
if record.status == "recognition_failed":
task = self._queue_recognition(record, ctx)
return {"import": self._require_import(import_id).to_dict(), "task": task.to_dict()}
if record.status == "validation_failed":
attempt, task = self._queue_validation(record, ctx)
return {"import": self._require_import(import_id).to_dict(), "attempt": attempt.to_dict(), "task": task.to_dict()}
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"advanced material import is not in a retryable state",
{"import_id": import_id, "status": record.status},
)
def cancel_import(self, import_id: str, ctx: RequestContext) -> dict[str, Any]:
record = self._require_import(import_id)
if record.status in {"accepted", "archived", "cancelled"}:
return record.to_dict()
if self.style_sets.is_style_set(record):
self.style_sets.cancel(record, ctx)
active_task_id = _optional_text(record.metadata.get("active_task_id"))
if active_task_id:
try:
self.queue_service.cancel_job(active_task_id, ctx, reason="advanced material import cancelled")
except ApiError:
pass
attempt = self.repository.get_active_attempt(import_id)
if attempt is not None:
self.repository.update_attempt(attempt.attempt_id, {"status": "cancelled", "decision": "cancelled"})
updated = self.repository.update_import(
import_id,
{"status": "cancelled", "metadata": {**record.metadata, "active_task_id": None}},
)
self.audit_service.record(
ctx=ctx,
action="cancel_advanced_material_import",
target_type="advanced_material_import",
target_id=import_id,
before_snapshot=record.to_dict(),
after_snapshot=updated.to_dict(),
)
return updated.to_dict()
def delete_import(self, import_id: str, ctx: RequestContext) -> dict[str, Any]:
record = self._require_import(import_id)
if record.accepted_material_id or self.repository.get_material_by_import(import_id) is not None:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"sealed advanced material imports cannot be deleted; archive the material instead",
{"import_id": import_id, "accepted_material_id": record.accepted_material_id},
)
media_uris = self._import_media_uris(record)
if record.status not in {"cancelled", "failed", "recognition_failed", "validation_failed"}:
self.cancel_import(import_id, ctx)
record = self._require_import(import_id)
before = record.to_dict()
try:
deleted = self.repository.delete_import(import_id)
except ValueError as exc:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
str(exc),
{"import_id": import_id},
) from None
if deleted is None:
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "advanced material import not found", {"import_id": import_id})
for uri in media_uris:
self._remove_uri(uri)
result = {
"import_id": import_id,
"deleted": True,
"previous_status": before.get("status"),
"removed_media_count": len(media_uris),
}
self.audit_service.record(
ctx=ctx,
action="delete_advanced_material_import",
target_type="advanced_material_import",
target_id=import_id,
before_snapshot=before,
metadata=result,
)
return result
def list_materials(self, *, page: int = 1, page_size: int = 30) -> dict[str, Any]:
normalized_page = max(int(page or 1), 1)
normalized_size = min(max(int(page_size or 30), 1), 100)
items, total = self.repository.list_materials(page=normalized_page, page_size=normalized_size)
return {
"items": [item.to_dict() for item in items],
"total": total,
"page": normalized_page,
"page_size": normalized_size,
}
def get_material(self, material_id: str):
material = self.repository.get_material(material_id)
if material is None or material.status == "archived":
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "advanced material not found", {"material_id": material_id})
return material
def archive_material(self, material_id: str, ctx: RequestContext):
before = self.get_material(material_id)
after = self.repository.archive_material(material_id)
if after is None:
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "advanced material not found", {"material_id": material_id})
self.audit_service.record(
ctx=ctx,
action="archive_advanced_material",
target_type="advanced_material",
target_id=material_id,
before_snapshot=before.to_dict(),
after_snapshot=after.to_dict(),
)
return after
def list_catalog(self, *, page: int = 1, page_size: int = 100) -> dict[str, Any]:
normalized_page = max(int(page or 1), 1)
normalized_size = min(max(int(page_size or 100), 1), 200)
advanced = self._all_advanced_materials()
advanced_total = len(advanced)
standard = self._all_standard_materials()
advanced_items = [
{**item.to_dict(), "library_kind": "advanced", "priority": ADVANCED_MATERIAL_PRIORITY}
for item in advanced
if item.status == "active"
]
standard_items = [
{
**item.to_dict(),
"library_kind": "standard",
"priority": 0,
}
for item in standard
if item.recognition_status == "confirmed"
]
merged = [*advanced_items, *standard_items]
offset = (normalized_page - 1) * normalized_size
return {
"items": merged[offset : offset + normalized_size],
"total": len(merged),
"page": normalized_page,
"page_size": normalized_size,
"advanced_total": advanced_total,
"standard_total": sum(1 for item in standard if item.recognition_status == "confirmed"),
}
def _all_advanced_materials(self) -> list[Any]:
result: list[Any] = []
page = 1
while True:
items, total = self.repository.list_materials(page=page, page_size=200)
result.extend(items)
if len(result) >= total or not items:
return result
page += 1
def _all_standard_materials(self) -> list[Material]:
result: list[Material] = []
page = 1
while True:
items, total = self.material_repository.list_materials(page=page, page_size=100)
result.extend(items)
if len(result) >= total or not items:
return result
page += 1
def execute_task(self, task: GenerationTask, ctx: RequestContext) -> WorkerTaskUpdate:
if task.task_type in {
"advanced_style_source_recognition",
"advanced_style_consensus",
"advanced_style_validation_generation",
}:
return self.style_sets.execute_task(task, ctx)
if task.task_type == "advanced_material_recognition":
return self._execute_recognition(task, ctx)
if task.task_type == "advanced_material_validation_generation":
return self._execute_validation(task, ctx)
raise RuntimeError(f"unsupported advanced material task type: {task.task_type}")
def handle_task_failure(self, task: GenerationTask, exc: Exception, ctx: RequestContext) -> None:
if task.task_type in {
"advanced_style_source_recognition",
"advanced_style_consensus",
"advanced_style_validation_generation",
}:
self.style_sets.handle_failure(task, exc, ctx)
return
import_id = _optional_text(task.metadata.get("advanced_material_import_id"))
if not import_id:
return
failure = _safe_failure(exc)
record = self.repository.get_import(import_id)
if record is None:
return
if record.status in {"cancelled", "accepted", "archived"}:
return
if task.task_type == "advanced_material_recognition":
self.repository.update_import(
import_id,
{
"status": "recognition_failed",
"error": failure,
"metadata": {**record.metadata, "active_task_id": None},
},
)
elif task.task_type == "advanced_material_validation_generation":
attempt_id = _optional_text(task.metadata.get("advanced_material_attempt_id"))
if attempt_id:
attempt = self.repository.get_attempt(attempt_id)
if attempt is not None and attempt.status in ATTEMPT_ACTIVE_STATUSES:
self.repository.update_attempt(attempt_id, {"status": "failed", "error": failure})
self.repository.update_import(
import_id,
{
"status": "validation_failed",
"error": failure,
"metadata": {**record.metadata, "active_task_id": None},
},
)
self.audit_service.record(
ctx=ctx,
action="advanced_material_task_failed",
target_type="advanced_material_import",
target_id=import_id,
metadata={"task_id": task.task_id, "task_type": task.task_type, "failure": failure},
)
def _execute_recognition(self, task: GenerationTask, ctx: RequestContext) -> WorkerTaskUpdate:
import_id = str(task.metadata.get("advanced_material_import_id") or "").strip()
record = self._require_import(import_id)
if record.status not in {"recognition_queued", "recognizing"}:
return WorkerTaskUpdate(result={"import_id": import_id, "status": record.status})
self._ensure_task_active(task, record)
record = self.repository.update_import_if_status(
import_id,
{"recognition_queued", "recognizing"},
{"status": "recognizing", "error": None},
)
if record is None:
raise AdvancedMaterialTaskCancelled("advanced material recognition no longer owns the import")
route_name = record.recognition_model_route or self._recognition_route()
provider = self.model_provider_runtime.vision_provider_for_route(
{
"route_name": route_name,
"modality": "vision_recognition",
"material_id": import_id,
"image_uri": record.source_image_uri,
}
)
if provider is None:
raise ApiError(
ErrorCode.MODEL_CAPABILITY_UNCONFIRMED,
"advanced material vision route is not configured or unavailable",
{"route_name": route_name, "modality": "vision_recognition"},
)
material = Material(
material_id=import_id,
category_id=record.category_id,
display_name=record.display_name,
image_uri=record.source_image_uri,
thumbnail_uri=record.source_thumbnail_uri,
prompt=None,
negative_prompt=None,
tags=[],
recognition_status="pending_recognition",
metadata={"advanced_material": True},
created_at=record.created_at,
updated_at=record.updated_at,
)
image_data_url, content_type, size_bytes = _storage_image_data_url(
record.source_image_uri,
material.metadata,
self.storage,
)
request = VisionRecognitionRequest(
display_name=record.display_name,
image_uri=image_data_url,
thumbnail_uri=None,
prompt=None,
negative_prompt=None,
tags=(),
metadata={
"advanced_material": True,
"recognition_instruction": self._recognition_instruction(record),
"vision_input": {
"source_uri": record.source_image_uri,
"content_type": content_type,
"size_bytes": size_bytes,
},
},
)
try:
recognition = provider.recognize_material(request)
except VisionProviderError as exc:
raise ApiError(
ErrorCode.GENERATION_FAILED,
"advanced material recognition failed",
{**_vision_provider_error(exc), "route_name": route_name},
) from None
category = self.material_repository.get_category(record.category_id) if record.category_id else None
try:
structures = self.normalization_service.normalize_recognition(
recognition.structured_data,
prompt=recognition.prompt,
negative_prompt=recognition.negative_prompt,
tags=recognition.tags,
confidence=recognition.confidence,
provider_id=recognition.provider_id,
model=recognition.model,
route_name=route_name,
category_hint=category.name if category else None,
)
except MaterialNormalizationError as exc:
raise ApiError(
ErrorCode.GENERATION_FAILED,
"advanced material recognition returned an invalid structured result",
{"route_name": route_name, "error_type": "invalid_structured_analysis"},
) from exc
result = {
"recognition": _recognition_metadata(recognition, route_name=route_name),
**structures,
}
self._ensure_task_active(task, self._require_import(import_id))
updated = self.repository.update_import_if_status(
import_id,
{"recognizing"},
{
"status": "ready_for_validation",
"recognition_prompt": recognition.prompt,
"recognition_negative_prompt": recognition.negative_prompt,
"recognition_tags": recognition.tags,
"recognition_result": result,
"error": None,
"metadata": {**record.metadata, "active_task_id": None},
},
)
if updated is None:
raise AdvancedMaterialTaskCancelled("advanced material recognition result arrived after cancellation")
try:
attempt, next_task = self._queue_validation(updated, ctx)
except Exception as exc:
self.repository.update_import(
import_id,
{
"status": "validation_failed",
"error": _safe_failure(exc),
"metadata": {**updated.metadata, "active_task_id": None},
},
)
return WorkerTaskUpdate(
result={
"import_id": import_id,
"recognition_status": "completed",
"validation_queue_status": "failed",
},
metadata={"pipeline_stage": "validation_queue_failed"},
)
return WorkerTaskUpdate(
result={
"import_id": import_id,
"recognition_status": "completed",
"attempt_id": attempt.attempt_id,
"next_task_id": next_task.task_id,
},
metadata={"pipeline_stage": "recognition_completed"},
)
def _execute_validation(self, task: GenerationTask, ctx: RequestContext) -> WorkerTaskUpdate:
import_id = str(task.metadata.get("advanced_material_import_id") or "").strip()
attempt_id = str(task.metadata.get("advanced_material_attempt_id") or "").strip()
record = self._require_import(import_id)
attempt = self._require_attempt(import_id, attempt_id)
if attempt.status == "awaiting_review" and attempt.validation_image_uri:
return WorkerTaskUpdate(result={"import_id": import_id, "attempt_id": attempt_id, "status": "awaiting_review"})
if attempt.status not in {"queued", "running"}:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"advanced material validation attempt is not executable",
{"attempt_id": attempt_id, "status": attempt.status},
)
self._ensure_task_active(task, record, attempt=attempt)
claimed = self.repository.mark_attempt_running(import_id, attempt_id)
if claimed is None:
raise AdvancedMaterialTaskCancelled("advanced material validation no longer owns the import")
record, attempt = claimed
requested_route = attempt.model_route or self._generation_route()
governance = self._govern_validation_prompt(
record=record,
attempt=attempt,
requested_route=requested_route,
ctx=ctx,
)
route_name = str(governance["selected_route"])
resolved_route = self._resolve_generation_route(route_name)
cost_guard = self._check_validation_budget(route_name, resolved_route)
attempt_metadata = {
**attempt.metadata,
"prompt_governance": governance["snapshot"],
**({"cost_guard": cost_guard} if cost_guard else {}),
}
self.repository.update_attempt(attempt_id, {"metadata": attempt_metadata})
node = WorkflowNode(
node_id=f"advanced-material:{attempt_id}",
workflow_id=f"advanced-material:{import_id}",
node_key="advanced_material_validation",
title="进阶素材还原验证",
description=None,
step_name="validation",
node_type="generation",
status="running",
branch_name="main",
prompt=governance["prompt"],
negative_prompt=governance["negative_prompt"],
model_route=route_name,
selected_image_id=None,
sort_order=0,
metadata={"advanced_material": True},
created_at=attempt.created_at,
updated_at=attempt.updated_at,
)
request = {
"count": 1,
"aspect_ratio": "1:1",
"quality": "standard",
"seed": int(attempt.seed or DEFAULT_VALIDATION_SEED),
"model_route": route_name,
"resolved_model_route": resolved_route,
"allow_provider_fallback": False,
"expanded_prompt": governance["prompt"],
"expanded_negative_prompt": governance["negative_prompt"],
"prompt_governance": governance["snapshot"],
**({"cost_guard": cost_guard} if cost_guard else {}),
# Deliberately no input_images/image field: the validation render
# measures the text description rather than image-to-image copying.
"output_scope": {
"kind": "advanced_material_validation",
"import_id": import_id,
"attempt_id": attempt_id,
"attempt_number": attempt.attempt_number,
},
}
assets: list[Any] = []
try:
try:
assets = self.single_flow_engine.generate(node, task, request)
except ImageProviderError as exc:
fallback = self._content_safety_fallback(
exc=exc,
runtime_request=request,
governance=governance,
requested_route=requested_route,
record=record,
ctx=ctx,
)
if fallback is None:
raise
route_name = fallback["model_route"]
resolved_route = fallback["resolved_model_route"]
request = fallback["request"]
attempt_metadata = {
**attempt_metadata,
"route_fallback": fallback["route_fallback"],
**({"fallback_cost_guard": fallback["cost_guard"]} if fallback.get("cost_guard") else {}),
}
self.repository.update_attempt(attempt_id, {"metadata": attempt_metadata})
assets = self.single_flow_engine.generate(node, task, request)
except Exception:
for asset in assets:
self._remove_uri(str(getattr(asset, "image_uri", "") or ""))
self._remove_uri(str(getattr(asset, "thumbnail_uri", "") or ""))
raise
if len(assets) != 1:
raise ImageProviderError(
"advanced material validation must return exactly one image",
provider_id=str(resolved_route.get("provider_id") or "unknown"),
error_type="invalid_response",
)
asset = assets[0]
route_provider = resolved_route.get("provider") if isinstance(resolved_route.get("provider"), dict) else {}
provider_id = asset.metadata.get("provider_id") or resolved_route.get("provider_id")
provider_model = asset.metadata.get("provider_model") or resolved_route.get("model_id")
usage = asset.metadata.get("usage") or {}
latest_attempt = self.repository.get_attempt(attempt_id) or attempt
billable_metadata = {
**latest_attempt.metadata,
**attempt_metadata,
"generation": asset.metadata,
"provider_base_url_present": bool(route_provider.get("base_url")),
"effective_model_route": route_name,
}
# Persist billable attribution before the publication CAS. If the
# user cancelled while the provider was running, the usage remains
# auditable even though the late image is deleted instead of revived.
self.repository.update_attempt(
attempt_id,
{
"model_route": route_name,
"provider_id": provider_id,
"provider_model": provider_model,
"width": asset.width,
"height": asset.height,
"usage": usage,
"metadata": billable_metadata,
},
)
completed = self.repository.complete_attempt_if_active(
import_id,
attempt_id,
attempt_payload={
"model_route": route_name,
"validation_image_uri": asset.image_uri,
"validation_thumbnail_uri": asset.thumbnail_uri,
"provider_id": provider_id,
"provider_model": provider_model,
"width": asset.width,
"height": asset.height,
"usage": usage,
"metadata": billable_metadata,
},
import_payload={
"metadata": {
**record.metadata,
"active_task_id": None,
"last_validation_governance": governance["snapshot"],
},
},
)
if completed is None:
self._remove_uri(asset.image_uri)
self._remove_uri(asset.thumbnail_uri)
raise AdvancedMaterialTaskCancelled("advanced material validation result arrived after cancellation")
updated_import, updated_attempt = completed
self.audit_service.record(
ctx=ctx,
action="complete_advanced_material_validation",
target_type="advanced_material_validation_attempt",
target_id=attempt_id,
after_snapshot=updated_attempt.to_dict(),
metadata={"import_id": import_id, "task_id": task.task_id},
)
return WorkerTaskUpdate(
result={
"import_id": import_id,
"attempt_id": attempt_id,
"status": updated_import.status,
"validation_image_uri": asset.image_uri,
"validation_thumbnail_uri": asset.thumbnail_uri,
},
metadata={"pipeline_stage": "awaiting_human_review"},
)
def _govern_validation_prompt(
self,
*,
record: Any,
attempt: Any,
requested_route: str,
ctx: RequestContext,
) -> dict[str, Any]:
prompt = str(attempt.prompt or record.recognition_prompt or "").strip()
negative_prompt = str(attempt.negative_prompt or record.recognition_negative_prompt or "").strip()
if not prompt:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"advanced material validation prompt is empty",
{"import_id": record.import_id, "attempt_id": attempt.attempt_id},
)
routing_context = self._validation_routing_context(record, ctx)
if self.prompt_moderation_service:
moderation = self.prompt_moderation_service.moderate(
original_prompt=prompt,
translated_prompt=prompt,
final_prompt=prompt,
negative_prompt=negative_prompt,
reference_bindings=[],
)
else:
moderation = PromptModerationDecision(
"safe",
1.0,
[],
["moderation_not_configured"],
"allow",
None,
"none",
None,
"",
)
if self.generation_route_service:
route = self.generation_route_service.decide(
requested_route,
moderation,
entrypoint=routing_context["entrypoint"],
user_id=routing_context["user_id"],
group_id=routing_context["group_id"],
permission_context=routing_context["content_permissions"],
)
route_snapshot = route.to_dict()
selected_route = route.selected_route
allowed = route.allowed
requires_confirmation = route.requires_confirmation
route_reason = route.reason
# The dedicated advanced-material assignment is intentionally
# stronger than the global safe route. Only adult content may
# leave the requested validation route for the configured NSFW
# route.
if allowed and moderation.level in {"safe", "sensitive"}:
if selected_route != requested_route:
route_snapshot["global_safe_route_ignored"] = selected_route
selected_route = requested_route
route_snapshot["selected_route"] = requested_route
route_snapshot["reason"] = "advanced_material_requested_route"
route_reason = "advanced_material_requested_route"
else:
selected_route = requested_route if moderation.allowed else None
allowed = moderation.allowed
requires_confirmation = moderation.level == "uncertain"
route_reason = "static_route"
route_snapshot = {
"requested_route": requested_route,
"moderation_level": moderation.level,
"selected_route": selected_route,
"reason": route_reason,
"fallback_route": None,
"allowed": allowed,
"requires_confirmation": requires_confirmation,
}
snapshot = {
"moderation": moderation.to_dict(),
"route_decision": route_snapshot,
"entrypoint": routing_context["entrypoint"],
}
if not allowed or not selected_route:
if moderation.level in {"terror_prohibited", "violence_prohibited", "prohibited"}:
try:
self.audit_service.record(
ctx=ctx,
action="advanced_material_content_safety_blocked",
target_type="advanced_material_validation_attempt",
target_id=attempt.attempt_id,
metadata={
"import_id": record.import_id,
"priority": "high" if moderation.level in {"terror_prohibited", "violence_prohibited"} else "normal",
"moderation_level": moderation.level,
"reason_codes": moderation.reason_codes,
"rules_version": moderation.rules_version,
"entrypoint": routing_context["entrypoint"],
},
)
except Exception:
pass
self.repository.update_attempt(attempt.attempt_id, {"metadata": {**attempt.metadata, "prompt_governance": snapshot}})
raise ApiError(
ErrorCode.VALIDATION_FAILED,
moderation.warning or ("内容需要确认后才能生成" if requires_confirmation else "内容审核未通过,未创建验证图任务"),
{
"moderation_level": moderation.level,
"reason_codes": moderation.reason_codes,
"route_reason": route_reason,
"requires_confirmation": requires_confirmation,
"warning": moderation.warning,
},
)
return {
"prompt": prompt,
"negative_prompt": negative_prompt,
"selected_route": selected_route,
"moderation": moderation,
"snapshot": snapshot,
"routing_context": routing_context,
}
def _content_safety_fallback(
self,
*,
exc: ImageProviderError,
runtime_request: dict[str, Any],
governance: dict[str, Any],
requested_route: str,
record: Any,
ctx: RequestContext,
) -> dict[str, Any] | None:
failure = self.failure_classifier.classify(exc)
if failure.get("failure_class") != "content_safety_rejection":
return None
if not self.prompt_moderation_service or not self.generation_route_service:
return None
if isinstance(runtime_request.get("route_fallback"), dict) and runtime_request["route_fallback"].get("attempted"):
return None
prompt = str(runtime_request.get("expanded_prompt") or "").strip()
negative_prompt = str(runtime_request.get("expanded_negative_prompt") or "").strip()
moderation = self.prompt_moderation_service.moderate(
original_prompt=prompt,
translated_prompt=prompt,
final_prompt=prompt,
negative_prompt=negative_prompt,
reference_bindings=[],
)
if moderation.level in {"terror_prohibited", "violence_prohibited", "prohibited", "uncertain"}:
return None
if moderation.level != "adult_allowed" and failure.get("safety_reason") != "adult":
return None
provider_signal_moderation = moderation
if moderation.level != "adult_allowed":
provider_signal_moderation = replace(
moderation,
level="adult_allowed",
categories=[*moderation.categories, "provider_content_safety_rejection"],
reason_codes=[*moderation.reason_codes, "provider_classified_prompt_as_adult"],
action="route_nsfw",
warning=None,
)
routing_context = self._validation_routing_context(record, ctx)
route = self.generation_route_service.decide(
requested_route,
provider_signal_moderation,
entrypoint=routing_context["entrypoint"],
user_id=routing_context["user_id"],
group_id=routing_context["group_id"],
permission_context=routing_context["content_permissions"],
)
current_route = str(runtime_request.get("model_route") or "").strip()
if not route.allowed or not route.selected_route or route.selected_route == current_route:
return None
resolved_route = self._resolve_generation_route(route.selected_route)
# The first provider may already have accepted and billed the request
# before returning a content-safety rejection. Reserve two requests
# for the fallback check so the budget cannot be bypassed by the
# automatic second call.
cost_guard = self._check_validation_budget(
route.selected_route,
resolved_route,
planned_task_count=2,
)
fallback_record = {
"attempted": True,
"initial_route": current_route,
"failure_class": failure,
"moderation_recheck": moderation.to_dict(),
"provider_signal_moderation": provider_signal_moderation.to_dict(),
"fallback_route": route.selected_route,
"fallback_reason": route.reason,
}
return {
"model_route": route.selected_route,
"resolved_model_route": resolved_route,
"route_fallback": fallback_record,
"cost_guard": cost_guard,
"request": {
**runtime_request,
"model_route": route.selected_route,
"resolved_model_route": resolved_route,
"route_fallback": fallback_record,
"allow_provider_fallback": False,
**({"cost_guard": cost_guard} if cost_guard else {}),
},
}
def _resolve_generation_route(self, route_name: str) -> dict[str, Any]:
resolution = self.model_provider_service.resolve_route(route_name, modality="image_generation")
if not resolution:
raise ApiError(
ErrorCode.MODEL_CAPABILITY_UNCONFIRMED,
"advanced material validation image route is not configured",
{"route_name": route_name, "modality": "image_generation"},
)
return {
**resolution,
"status": "resolved",
"route_name": str(resolution.get("route_name") or route_name),
}
def _check_validation_budget(
self,
route_name: str,
resolved_route: dict[str, Any],
*,
planned_task_count: int = 1,
) -> dict[str, Any] | None:
advanced_config = self.config.get("advanced_materials") if isinstance(self.config.get("advanced_materials"), dict) else {}
cost_guard_config = self.config.get("cost_guard") if isinstance(self.config.get("cost_guard"), dict) else {}
budget = advanced_config.get("cost_budget") if isinstance(advanced_config.get("cost_budget"), dict) else None
if budget is None and isinstance(cost_guard_config.get("advanced_materials"), dict):
budget = cost_guard_config["advanced_materials"]
if not budget or not self.cost_guard_service or not bool(budget.get("enabled", True)):
return None
unit_prices = budget.get("unit_prices") if isinstance(budget.get("unit_prices"), dict) else None
price_key = str(budget.get("price_key") or "").strip()
if unit_prices is None and price_key:
unit_prices = {
price_key: {
"per_request": _optional_nonnegative_float(budget.get("per_request")),
"per_image": _optional_nonnegative_float(budget.get("per_image")),
"per_1k_tokens": _optional_nonnegative_float(budget.get("per_1k_tokens")),
}
}
guard = self.cost_guard_service.check_generation_budget(
provider_id=resolved_route.get("provider_id"),
provider_model=resolved_route.get("model_id") or route_name,
model_route=route_name,
planned_task_count=max(int(planned_task_count), 1),
planned_image_count=1,
planned_total_tokens=int(budget.get("planned_total_tokens") or 0),
max_task_count=budget.get("max_task_count"),
max_image_count=budget.get("max_image_count"),
max_estimated_cost=budget.get("max_estimated_cost"),
days=budget.get("days"),
unit_prices=unit_prices,
)
if not guard.get("allowed"):
raise ApiError(ErrorCode.VALIDATION_FAILED, "advanced material validation budget exceeded", guard)
return guard
def _validation_routing_context(self, record: Any, ctx: RequestContext) -> dict[str, Any]:
stored = record.metadata.get("governance_context") if isinstance(record.metadata.get("governance_context"), dict) else {}
permissions = stored.get("content_permissions") if isinstance(stored.get("content_permissions"), dict) else {}
user_id = _optional_text(stored.get("user_id")) or ctx.actor_id
group_id = _optional_text(stored.get("group_id"))
access = self.config.get("chat_access") if isinstance(self.config.get("chat_access"), dict) else {}
adult_users = {str(value).strip() for value in access.get("adult_user_allowlist", []) if str(value).strip()}
adult_groups = {str(value).strip() for value in access.get("adult_group_allowlist", []) if str(value).strip()}
return {
"entrypoint": str(stored.get("entrypoint") or _entrypoint_from_context(ctx)),
"user_id": user_id,
"group_id": group_id,
"content_permissions": {
"adult_user_allowed": bool(user_id and user_id in adult_users),
**({"adult_group_allowed": bool(group_id in adult_groups)} if group_id else {}),
"quota_allowed": bool(permissions.get("quota_allowed", True)),
},
}
def _queue_recognition(self, record, ctx: RequestContext) -> GenerationTask:
if record.status in IMPORT_ACTIVE_STATUSES and _optional_text(record.metadata.get("active_task_id")):
try:
existing = self.queue_service.get_job(str(record.metadata["active_task_id"]))
except ApiError:
existing = None
if existing is not None and existing.status in {"queued", "running"}:
return existing
task = self.queue_service.create_task(
{
"task_type": "advanced_material_recognition",
"status": "queued",
"model_route": record.recognition_model_route or self._recognition_route(),
"idempotency_key": f"advanced-material-recognition:{record.import_id}:{record.prompt_revision}",
"request": {"import_id": record.import_id, "operation": "recognize"},
"metadata": {
"source": "advanced_material",
"advanced_material_import_id": record.import_id,
"stage": "recognition",
"task_summary": f"进阶素材/{record.display_name}/识别",
},
},
ctx,
)
self.repository.update_import(
record.import_id,
{
"status": "recognition_queued",
"error": None,
"metadata": {**record.metadata, "active_task_id": task.task_id},
},
)
return task
def _queue_validation(self, record, ctx: RequestContext):
if record.status in IMPORT_ACTIVE_STATUSES:
active = self.repository.get_active_attempt(record.import_id)
if active is not None and active.task_id:
task = self.queue_service.get_job(active.task_id)
if task.status in {"queued", "running"}:
return active, task
if not record.recognition_prompt:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"advanced material must be recognized before validation generation",
{"import_id": record.import_id, "status": record.status},
)
if record.status not in {"ready_for_validation", "adjustment_required", "validation_failed"}:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"advanced material is not ready to create a validation attempt",
{"import_id": record.import_id, "status": record.status},
)
attempt_id = f"advattempt_{uuid4().hex}"
route_name = _optional_text(record.metadata.get("generation_model_route")) or self._generation_route()
attempt = self.repository.create_attempt(
{
"attempt_id": attempt_id,
"import_id": record.import_id,
"status": "queued",
"adjustment_text": _latest_adjustment(record.metadata),
"prompt": record.recognition_prompt,
"negative_prompt": record.recognition_negative_prompt,
"model_route": route_name,
"seed": DEFAULT_VALIDATION_SEED,
"width": 1024,
"height": 1024,
"metadata": {"prompt_revision": record.prompt_revision},
}
)
attempt_number = attempt.attempt_number
try:
task = self.queue_service.create_task(
{
"task_type": "advanced_material_validation_generation",
"status": "queued",
"model_route": route_name,
"idempotency_key": f"advanced-material-validation:{attempt_id}",
"request": {"import_id": record.import_id, "attempt_id": attempt_id, "operation": "validate"},
"metadata": {
"source": "advanced_material",
"advanced_material_import_id": record.import_id,
"advanced_material_attempt_id": attempt_id,
"attempt_number": attempt_number,
"stage": "validation_generation",
"task_summary": f"进阶素材/{record.display_name}/第{attempt_number}轮验证",
},
},
ctx,
)
attempt = self.repository.update_attempt(attempt_id, {"task_id": task.task_id})
self.repository.update_import(
record.import_id,
{
"status": "validation_queued",
"current_attempt_id": attempt_id,
"error": None,
"metadata": {**record.metadata, "active_task_id": task.task_id},
},
)
except Exception as exc:
self.repository.update_attempt(attempt_id, {"status": "failed", "error": _safe_failure(exc)})
self.repository.update_import(
record.import_id,
{
"status": "validation_failed",
"error": _safe_failure(exc),
"metadata": {**record.metadata, "active_task_id": None},
},
)
raise
return attempt, task
def _apply_adjustment(self, record, adjustment: str, ctx: RequestContext):
prompt = _append_adjustment(record.recognition_prompt, adjustment)
history = list(record.metadata.get("adjustment_history") or [])
history.append(
{
"revision": int(record.prompt_revision or 0) + 1,
"text": adjustment,
"actor_id": ctx.actor_id,
}
)
return self.repository.update_import(
record.import_id,
{
"status": "adjustment_required",
"recognition_prompt": prompt,
"prompt_revision": int(record.prompt_revision or 0) + 1,
"metadata": {
**record.metadata,
"adjustment_history": history[-20:],
"governance_context": _governance_context(self.config, ctx),
},
},
)
def _recognition_instruction(self, record) -> str:
prompts = self.config.get("recognition_prompts") if isinstance(self.config.get("recognition_prompts"), dict) else {}
base = str(prompts.get("default_instruction") or "").strip()
category = self.material_repository.get_category(record.category_id) if record.category_id else None
category_hint = f"User selected category: {category.name}." if category else ""
return "\n\n".join(
part
for part in (
base,
category_hint,
"Extract observable colors, material, texture, silhouette, construction, patterns, trim and small details as faithfully as possible.",
"Produce a standalone text-to-image prompt. Do not assume the source image will be supplied to the image generator.",
)
if part
)
def _recognition_route(self) -> str:
assignments = self.config.get("model_assignments") if isinstance(self.config.get("model_assignments"), dict) else {}
vision = self.config.get("vision") if isinstance(self.config.get("vision"), dict) else {}
provider = vision.get("provider") if isinstance(vision.get("provider"), dict) else {}
return str(
assignments.get("advanced_material_recognition")
or assignments.get("material_recognition")
or provider.get("route_name")
or vision.get("default_route")
or "material_vlm"
).strip()
def _consensus_route(self) -> str:
assignments = self.config.get("model_assignments") if isinstance(self.config.get("model_assignments"), dict) else {}
return str(
assignments.get("advanced_style_consensus")
or assignments.get("advanced_material_recognition")
or assignments.get("material_recognition")
or self._recognition_route()
or "material_vlm"
).strip()
def _generation_route(self) -> str:
assignments = self.config.get("model_assignments") if isinstance(self.config.get("model_assignments"), dict) else {}
generation = self.config.get("generation") if isinstance(self.config.get("generation"), dict) else {}
provider = generation.get("provider") if isinstance(generation.get("provider"), dict) else {}
return str(
assignments.get("advanced_material_validation_generation")
or assignments.get("quick_generation")
or generation.get("default_model")
or provider.get("route_name")
or "image_default"
).strip()
def _persist_source(
self,
*,
import_id: str,
image_data_url: str,
image_uri: str,
filename: str | None,
declared_content_type: str | None,
declared_size: int | None,
) -> tuple[str, str, int, str]:
if image_data_url:
content, detected_type, detected_extension = _decode_upload_data_url(image_data_url)
elif image_uri:
source_path = self.storage.ensure_file(image_uri)
try:
reported_size = source_path.stat().st_size
if reported_size > MAX_UPLOAD_BYTES:
raise ApiError(
ErrorCode.UPLOAD_TOO_LARGE,
"advanced material source exceeds the size limit",
{"size_bytes": reported_size, "max_size_bytes": MAX_UPLOAD_BYTES},
)
with source_path.open("rb") as handle:
content = handle.read(MAX_UPLOAD_BYTES + 1)
except ApiError:
raise
except OSError as exc:
raise ApiError(
ErrorCode.MEDIA_NOT_FOUND,
"advanced material source image could not be read",
{"uri": image_uri, "exception_type": exc.__class__.__name__},
) from None
detected = detect_image_format(content)
if detected is None:
raise ApiError(ErrorCode.UNSUPPORTED_FILE_TYPE, "advanced material source is not a supported image")
detected_type = detected.mime_type
detected_extension = detected.extension
filename = filename or source_path.name
else:
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"image_data_url or image_uri is required",
{"fields": ["image_data_url", "image_uri"]},
)
if len(content) > MAX_UPLOAD_BYTES:
raise ApiError(
ErrorCode.UPLOAD_TOO_LARGE,
"advanced material upload exceeds the size limit",
{"size_bytes": len(content), "max_size_bytes": MAX_UPLOAD_BYTES},
)
if declared_size is not None and declared_size != len(content):
raise ApiError(
ErrorCode.VALIDATION_FAILED,
"declared upload size does not match image bytes",
{"declared_size_bytes": declared_size, "actual_size_bytes": len(content)},
)
if declared_content_type and declared_content_type != detected_type:
raise ApiError(
ErrorCode.UNSUPPORTED_FILE_TYPE,
"upload content type does not match image bytes",
{"content_type": declared_content_type, "detected_content_type": detected_type},
)
filename_extension = _suffix(filename)
if filename_extension and filename_extension != detected_extension:
aliases = {(".jpg", ".jpeg"), (".jpeg", ".jpg")}
if (filename_extension, detected_extension) not in aliases:
raise ApiError(
ErrorCode.UNSUPPORTED_FILE_TYPE,
"upload filename extension does not match image bytes",
{"filename": filename, "detected_content_type": detected_type},
)
safe_name = filename or f"advanced-material{detected_extension}"
stem = PurePosixPath(safe_name).stem or "source"
destination_uri = f"storage://advanced_materials/sources/{import_id}/{uuid4().hex}-{stem}{detected_extension}"
path = self.storage.resolve_uri(destination_uri)
try:
path.parent.mkdir(parents=True, exist_ok=True)
temporary = path.with_suffix(f"{path.suffix}.part")
temporary.write_bytes(content)
temporary.replace(path)
except OSError as exc:
raise ApiError(
ErrorCode.STORAGE_WRITE_FAILED,
"advanced material source image could not be stored",
{"uri": destination_uri, "exception_type": exc.__class__.__name__},
) from None
return destination_uri, detected_type, len(content), safe_name
def _remove_uri(self, uri: str) -> None:
if not uri:
return
try:
self.storage.resolve_uri(uri).unlink(missing_ok=True)
except (ApiError, OSError):
pass
def _reconcile_import_task(self, record: Any) -> Any:
if self.style_sets.is_style_set(record):
return self.style_sets.reconcile_missing_tasks(record)
if record.status not in IMPORT_ACTIVE_STATUSES:
return record
task_id = _optional_text(record.metadata.get("active_task_id"))
task_missing = not task_id
if task_id:
try:
self.queue_service.get_job(task_id)
except ApiError:
task_missing = True
if not task_missing:
return record
stage = "validation_generation" if record.status in {"validation_queued", "validating"} else "recognition"
failure = {
"error_type": "queue_task_missing",
"message": "关联的队列记录已被删除;可重新入队或删除整个导入。",
"stage": stage,
"task_id": task_id,
"retryable": True,
}
if stage == "validation_generation":
attempt = self.repository.get_active_attempt(record.import_id)
if attempt is not None:
self.repository.update_attempt(
attempt.attempt_id,
{"status": "failed", "task_id": None, "error": failure},
)
status = "validation_failed"
else:
status = "recognition_failed"
return self.repository.update_import(
record.import_id,
{
"status": status,
"error": failure,
"metadata": {**record.metadata, "active_task_id": None},
},
) or record
def _import_media_uris(self, record: Any) -> set[str]:
values: set[str] = set()
def add(*items: Any) -> None:
for item in items:
uri = str(item or "").strip()
if uri.startswith("storage://advanced_materials/"):
values.add(uri)
add(record.source_image_uri, record.source_thumbnail_uri)
if self.style_sets.is_style_set(record):
for source in self.repository.list_style_sources(record.import_id):
add(source.source_image_uri, source.source_thumbnail_uri)
for attempt in self.repository.list_attempts(record.import_id):
add(attempt.validation_image_uri, attempt.validation_thumbnail_uri)
for case in self.repository.list_style_validation_cases(attempt.attempt_id):
add(case.validation_image_uri, case.validation_thumbnail_uri)
return values
def _ensure_task_active(self, task: GenerationTask, record: Any, *, attempt: Any | None = None) -> None:
if record.status in {"cancelled", "accepted", "archived"}:
raise AdvancedMaterialTaskCancelled(
f"advanced material import is no longer active: {record.status}"
)
active_task_id = _optional_text(record.metadata.get("active_task_id"))
if active_task_id and active_task_id != task.task_id:
raise AdvancedMaterialTaskCancelled("advanced material task was superseded")
if attempt is not None:
if attempt.status in {"cancelled", "accepted", "rejected", "failed"}:
raise AdvancedMaterialTaskCancelled(
f"advanced material validation attempt is no longer active: {attempt.status}"
)
if attempt.task_id and attempt.task_id != task.task_id:
raise AdvancedMaterialTaskCancelled("advanced material validation task was superseded")
try:
queued_task = self.queue_service.get_job(task.task_id)
except ApiError as exc:
raise AdvancedMaterialTaskCancelled("advanced material queue task no longer exists") from exc
if queued_task.status not in {"queued", "running", "retrying"}:
raise AdvancedMaterialTaskCancelled(
f"advanced material queue task is no longer active: {queued_task.status}"
)
def _require_import(self, import_id: str):
record = self.repository.get_import(import_id)
if record is None or record.status == "archived":
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "advanced material import not found", {"import_id": import_id})
return record
def _require_attempt(self, import_id: str, attempt_id: str):
attempt = self.repository.get_attempt(attempt_id)
if attempt is None or attempt.import_id != import_id:
raise ApiError(
ErrorCode.RESOURCE_NOT_FOUND,
"advanced material validation attempt not found",
{"import_id": import_id, "attempt_id": attempt_id},
)
return attempt
def create_advanced_material_service() -> AdvancedMaterialService:
database = Database(load_database_settings())
audit = AuditService(database)
config = load_config_payload()
# AstrBot may expose a stale/blank runtime default for newly-added plugin
# fields. The writable plugin-data config is the source of truth for this
# dedicated route because the settings page persists it there.
file_config = load_config_file_payload()
file_assignments = file_config.get("model_assignments") if isinstance(file_config.get("model_assignments"), dict) else {}
persisted_consensus_route = str(file_assignments.get("advanced_style_consensus") or "").strip()
if persisted_consensus_route:
config = {
**config,
"model_assignments": {
**(config.get("model_assignments") if isinstance(config.get("model_assignments"), dict) else {}),
"advanced_style_consensus": persisted_consensus_route,
},
}
model_service = ModelProviderService(ModelProviderRepository(database))
sync_generation_provider_from_config(model_service, config)
sync_vision_provider_from_config(model_service, config)
runtime = ModelProviderRuntime(model_service)
storage = VfsStorage()
model_assignments = config.get("model_assignments") if isinstance(config.get("model_assignments"), dict) else {}
governance_config = config.get("prompt_governance") if isinstance(config.get("prompt_governance"), dict) else {}
moderation_config = governance_config.get("moderation") if isinstance(governance_config.get("moderation"), dict) else {}
routing_config = governance_config.get("routing") if isinstance(governance_config.get("routing"), dict) else {}
moderation_route = str(
moderation_config.get("model_route")
or model_assignments.get("cross_review_primary")
or ""
).strip()
moderation_callable = (
runtime.structured_text_callable(moderation_route)
or astrbot_structured_text_callable(moderation_route)
) if moderation_route else None
if moderation_callable:
raw_moderation_callable = moderation_callable
moderation_callable = lambda request: raw_moderation_callable(
{**request, "purpose": "advanced material validation prompt content risk classification"}
)
return AdvancedMaterialService(
repository=AdvancedMaterialRepository(database),
material_repository=MaterialRepository(database),
queue_service=QueueService(JobRepository(database), audit, get_default_event_bus()),
audit_service=audit,
model_provider_service=model_service,
model_provider_runtime=runtime,
config=config,
storage=storage,
single_flow_engine=SingleFlowEngine(
storage=storage,
image_provider_factory=runtime.image_provider_for_route,
allow_mock_fallback=False,
),
prompt_moderation_service=PromptModerationService(moderation_config, moderation_callable),
generation_route_service=GenerationRouteService(routing_config),
cost_guard_service=CostGuardService(CostService(database)),
)
def _governance_context(config: dict[str, Any], ctx: RequestContext) -> dict[str, Any]:
access = config.get("chat_access") if isinstance(config.get("chat_access"), dict) else {}
adult_users = {
str(value).strip()
for value in access.get("adult_user_allowlist", [])
if str(value).strip()
}
actor_id = _optional_text(ctx.actor_id)
return {
"entrypoint": _entrypoint_from_context(ctx),
"user_id": actor_id,
"group_id": None,
"content_permissions": {
"adult_user_allowed": bool(actor_id and actor_id in adult_users),
"quota_allowed": True,
},
}
def _entrypoint_from_context(ctx: RequestContext) -> str:
value = f"{ctx.platform} {ctx.source}".lower()
if "qq" in value or "onebot" in value:
return "qq"
if "telegram" in value:
return "telegram"
if "discord" in value:
return "discord"
if "api" in value:
return "api"
return "web"
def _optional_score(value: Any) -> float | None:
if value in (None, ""):
return None
try:
score = float(value)
except (TypeError, ValueError):
raise ApiError(ErrorCode.VALIDATION_FAILED, "fidelity_score must be a number", {"field": "fidelity_score"}) from None
if score > 1.0:
score /= 100.0
return min(max(score, 0.0), 1.0)
def _optional_nonnegative_float(value: Any) -> float:
try:
return max(float(value or 0), 0.0)
except (TypeError, ValueError):
return 0.0
def _append_adjustment(prompt: str | None, adjustment: str) -> str:
base = str(prompt or "").strip()
requirement = adjustment.strip()
marker = "User fidelity adjustment"
return "\n\n".join(part for part in (base, f"{marker}: {requirement}") if part)
def _latest_adjustment(metadata: dict[str, Any]) -> str | None:
history = metadata.get("adjustment_history")
if not isinstance(history, list) or not history:
return None
last = history[-1]
return _optional_text(last.get("text")) if isinstance(last, dict) else None
def _safe_failure(exc: Exception) -> dict[str, Any]:
failure: dict[str, Any] = {
"error_type": exc.__class__.__name__,
"exception_type": exc.__class__.__name__,
"message": " ".join(str(exc).split())[:500] or exc.__class__.__name__,
}
if isinstance(exc, ApiError):
failure.update({"error_code": exc.error_code.value, "details": exc.details})
elif isinstance(exc, ImageProviderError):
failure.update(
{
"provider_id": exc.provider_id,
"status_code": exc.status_code,
"provider_error_type": exc.error_type,
}
)
return failure