create-windy 0.3.2 → 0.3.5

package/template/apps/embedding-server/src/southwind_embedding_server/adapter.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+
+import httpx
+
+from .config import EmbeddingConfig
+from .contracts import (
+    EmbeddingItem,
+    EmbeddingMetadata,
+    EmbeddingRequest,
+    EmbeddingResponse,
+    EmbeddingVector,
+    JsonValue,
+)
+from .error import SafeEmbeddingError
+from .image_input import load_image
+
+
+class EmbeddingAdapter:
+    def __init__(self, config: EmbeddingConfig) -> None:
+        self.config = config
+
+    @property
+    def available(self) -> bool:
+        return self.config.adapter_url is not None
+
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        self._authorize(request)
+        if not self.config.adapter_url:
+            raise SafeEmbeddingError(
+                "CAPABILITY_UNAVAILABLE",
+                "Embedding Adapter 未配置",
+                True,
+            )
+        if len(request.items) > min(request.limits.max_units, self.config.max_units):
+            raise budget("Embedding 批量数量超过 Runtime 上限")
+        missing = set(request.required_capabilities) - set(self.config.capabilities)
+        if missing:
+            raise SafeEmbeddingError(
+                "CAPABILITY_UNAVAILABLE",
+                "Embedding Deployment 缺少 Operation 所需能力",
+                True,
+            )
+        prepared, input_hashes = await self._prepare(request)
+        raw = await self._invoke(request, prepared)
+        vectors = validate_vectors(
+            raw,
+            request.items,
+            input_hashes,
+            self.config.dimensions,
+            self.config.normalized,
+        )
+        return EmbeddingResponse(
+            batch_id=batch_id(request, input_hashes, self.config),
+            items=vectors,
+            metadata=EmbeddingMetadata(
+                deployment_alias=self.config.deployment_alias,
+                model=self.config.model,
+                version=self.config.version,
+                dimensions=self.config.dimensions,
+                normalized=self.config.normalized,
+            ),
+        )
+
+    async def _prepare(
+        self,
+        request: EmbeddingRequest,
+    ) -> tuple[list[dict[str, JsonValue]], list[str]]:
+        artifacts = sum(item.source is not None for item in request.items)
+        if artifacts > (request.limits.max_artifacts or 0):
+            raise budget("Embedding 图片数量超过 Operation 上限")
+        if artifacts and request.limits.max_pixels_per_artifact is None:
+            raise budget("Embedding Operation 未声明图片像素上限")
+        prepared: list[dict[str, JsonValue]] = []
+        hashes: list[str] = []
+        remaining = request.limits.max_input_bytes
+        for item in request.items:
+            if item.text is not None:
+                body = item.text.encode()
+                remaining -= len(body)
+                if remaining < 0:
+                    raise budget("Embedding 文本超过输入上限")
+                hashes.append(hashlib.sha256(body).hexdigest())
+                prepared.append({"id": item.id, "text": item.text})
+                continue
+            if item.source is None or request.limits.max_pixels_per_artifact is None:
+                raise invalid("Embedding 图片输入无效")
+            encoded, digest = await load_image(
+                item.source,
+                self.config,
+                remaining,
+                request.limits.max_pixels_per_artifact,
+            )
+            remaining -= item.source.byte_size
+            hashes.append(digest)
+            prepared.append(
+                {
+                    "id": item.id,
+                    "image": {
+                        "mediaType": "image/png",
+                        "dataBase64": encoded,
+                    },
+                }
+            )
+        return prepared, hashes
+
+    async def _invoke(
+        self,
+        request: EmbeddingRequest,
+        items: list[dict[str, JsonValue]],
+    ) -> object:
+        url = self.config.adapter_url
+        if not url:
+            raise SafeEmbeddingError(
+                "CAPABILITY_UNAVAILABLE",
+                "Embedding Adapter 未配置",
+                True,
+            )
+        headers = (
+            {"authorization": f"Bearer {self.config.adapter_token}"}
+            if self.config.adapter_token
+            else {}
+        )
+        try:
+            async with httpx.AsyncClient(
+                timeout=httpx.Timeout(
+                    self.config.request_timeout_seconds,
+                    connect=self.config.connect_timeout_seconds,
+                )
+            ) as client:
+                response = await client.post(
+                    f"{url.rstrip('/')}/v1/embeddings",
+                    headers=headers,
+                    json={
+                        "deploymentAlias": self.config.deployment_alias,
+                        "model": self.config.model,
+                        "version": self.config.version,
+                        "dimensions": self.config.dimensions,
+                        "items": items,
+                        "options": request.options,
+                    },
+                )
+            response.raise_for_status()
+            if len(response.content) > request.limits.max_output_bytes:
+                raise budget("Embedding 输出超过上限")
+            return response.json()
+        except SafeEmbeddingError:
+            raise
+        except Exception as error:
+            raise SafeEmbeddingError(
+                "RUNTIME_UNAVAILABLE",
+                "Embedding Adapter 执行失败",
+                True,
+            ) from error
+
+    def _authorize(self, request: EmbeddingRequest) -> None:
+        if request.provider_egress.mode == "forbidden":
+            return
+        fields = (
+            request.provider_data_policy.envelope_fields
+            if request.provider_data_policy
+            else []
+        )
+        if (
+            not request.provider_data_policy
+            or not self.config.deployment_key
+            or request.provider_egress.deployment_key != self.config.deployment_key
+            or not any(item.get("field") == "embedding-input" for item in fields)
+        ):
+            raise SafeEmbeddingError(
+                "FORBIDDEN",
+                "Embedding Operation 未授权当前 Deployment",
+                False,
+            )
+
+
+def validate_vectors(
+    value: object,
+    inputs: list[EmbeddingItem],
+    hashes: list[str],
+    dimensions: int,
+    normalized: bool,
+) -> list[EmbeddingVector]:
+    vectors = value.get("vectors") if isinstance(value, dict) else None
+    if not isinstance(vectors, list) or len(vectors) != len(inputs):
+        raise invalid_output()
+    result: list[EmbeddingVector] = []
+    for index, (raw, expected) in enumerate(zip(vectors, inputs, strict=True)):
+        vector = raw.get("vector") if isinstance(raw, dict) else None
+        if (
+            not isinstance(raw, dict)
+            or raw.get("id") != expected.id
+            or not isinstance(vector, list)
+            or len(vector) != dimensions
+            or any(
+                not isinstance(item, int | float)
+                or isinstance(item, bool)
+                or not math.isfinite(item)
+                for item in vector
+            )
+        ):
+            raise invalid_output()
+        values = [float(item) for item in vector]
+        norm = math.sqrt(sum(item * item for item in values))
+        if normalized and abs(norm - 1) > 0.01:
+            raise invalid_output("Embedding 向量未按声明归一化")
+        result.append(
+            EmbeddingVector(
+                id=expected.id,
+                vector=values,
+                input_sha256=hashes[index],
+            )
+        )
+    return result
+
+
+def batch_id(
+    request: EmbeddingRequest,
+    hashes: list[str],
+    config: EmbeddingConfig,
+) -> str:
+    payload = json.dumps(
+        {
+            "operationKey": request.operation_key,
+            "ids": [item.id for item in request.items],
+            "hashes": hashes,
+            "options": request.options,
+            "deploymentAlias": config.deployment_alias,
+            "model": config.model,
+            "version": config.version,
+            "dimensions": config.dimensions,
+        },
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode()
+    return f"embed_{hashlib.sha256(payload).hexdigest()[:32]}"
+
+
+def invalid(message: str) -> SafeEmbeddingError:
+    return SafeEmbeddingError("INVALID_INPUT", message, False)
+
+
+def budget(message: str) -> SafeEmbeddingError:
+    return SafeEmbeddingError("BUDGET_EXCEEDED", message, False)
+
+
+def invalid_output(
+    message: str = "Embedding Adapter 输出无效",
+) -> SafeEmbeddingError:
+    return SafeEmbeddingError("OUTPUT_VALIDATION_FAILED", message, False)

package/template/apps/embedding-server/src/southwind_embedding_server/app.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import asyncio
+import hmac
+import os
+import uuid
+
+from fastapi import Depends, FastAPI, Header, HTTPException
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from .adapter import EmbeddingAdapter
+from .config import EmbeddingConfig
+from .contracts import EmbeddingRequest, EmbeddingResponse, ErrorResponse
+from .error import SafeEmbeddingError
+
+
+def create_app(
+    config: EmbeddingConfig,
+    adapter: EmbeddingAdapter | None = None,
+) -> FastAPI:
+    app = FastAPI(title="Southwind Embedding Runtime", docs_url=None, redoc_url=None)
+    runtime = adapter or EmbeddingAdapter(config)
+
+    def authorize(authorization: str | None = Header(default=None)) -> None:
+        provided = (authorization or "").removeprefix("Bearer ")
+        if not provided or not hmac.compare_digest(provided, config.internal_token):
+            raise HTTPException(status_code=403, detail="FORBIDDEN")
+
+    @app.get("/health/ready")
+    async def ready(_: None = Depends(authorize)) -> JSONResponse:
+        if not runtime.available:
+            return JSONResponse(
+                {"status": "unavailable", "capabilities": []},
+                status_code=503,
+            )
+        return JSONResponse(
+            {
+                "status": "ready",
+                "capabilities": list(config.capabilities),
+                "limits": {"maxUnits": config.max_units},
+                "deployment": {
+                    "alias": config.deployment_alias,
+                    "model": config.model,
+                    "version": config.version,
+                    "dimensions": config.dimensions,
+                    "normalized": config.normalized,
+                },
+            }
+        )
+
+    @app.post("/api/embeddings")
+    async def embed(
+        request: EmbeddingRequest,
+        idempotency_key: str = Header(alias="idempotency-key"),
+        _: None = Depends(authorize),
+    ) -> EmbeddingResponse:
+        if not idempotency_key.strip() or len(idempotency_key) > 160:
+            raise HTTPException(status_code=400, detail="INVALID_INPUT")
+        try:
+            async with asyncio.timeout(request.limits.max_duration_seconds):
+                return await runtime.embed(request)
+        except TimeoutError as error:
+            raise SafeEmbeddingError(
+                "RUNTIME_UNAVAILABLE",
+                "Embedding 执行超时",
+                True,
+            ) from error
+
+    @app.exception_handler(HTTPException)
+    async def http_error(_request: object, error: HTTPException) -> JSONResponse:
+        code = str(error.detail)
+        return safe_error(code, "Embedding 请求被拒绝", error.status_code, False)
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_error(
+        _request: object,
+        _error: RequestValidationError,
+    ) -> JSONResponse:
+        return safe_error("INVALID_INPUT", "Embedding 请求格式无效", 400, False)
+
+    @app.exception_handler(SafeEmbeddingError)
+    async def embedding_error(
+        _request: object,
+        error: SafeEmbeddingError,
+    ) -> JSONResponse:
+        return safe_error(
+            error.code,
+            error.safe_message,
+            error_status(error.code),
+            error.retryable,
+        )
+
+    return app
+
+
+def error_status(code: str) -> int:
+    if code == "FORBIDDEN":
+        return 403
+    if code == "RUN_CONFLICT":
+        return 409
+    if code in {"CAPABILITY_UNAVAILABLE", "RUNTIME_UNAVAILABLE"}:
+        return 503
+    return 400
+
+
+def safe_error(code: str, message: str, status: int, retryable: bool) -> JSONResponse:
+    return JSONResponse(
+        ErrorResponse(
+            code=code,
+            message=message,
+            request_id=f"embedding_{uuid.uuid4().hex}",
+            retryable=retryable,
+        ).model_dump(by_alias=True),
+        status_code=status,
+    )
+
+
+app = create_app(EmbeddingConfig.from_environment(dict(os.environ)))

package/template/apps/embedding-server/src/southwind_embedding_server/config.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import ipaddress
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+
+@dataclass(frozen=True)
+class EmbeddingConfig:
+    internal_token: str
+    artifact_url: str
+    adapter_url: str | None
+    adapter_token: str | None
+    deployment_key: str | None
+    deployment_alias: str
+    model: str
+    version: str
+    dimensions: int
+    normalized: bool
+    capabilities: tuple[str, ...]
+    max_units: int = 256
+    connect_timeout_seconds: float = 5
+    request_timeout_seconds: float = 120
+
+    @classmethod
+    def from_environment(cls, environment: dict[str, str]) -> EmbeddingConfig:
+        artifact_url = environment.get(
+            "EMBEDDING_ARTIFACT_URL",
+            "http://server:9747/api/internal/ai/artifacts",
+        ).strip()
+        validate_intranet_url(artifact_url)
+        adapter_url = environment.get("EMBEDDING_ADAPTER_URL", "").strip() or None
+        if adapter_url:
+            validate_intranet_url(adapter_url)
+        return cls(
+            internal_token=required(environment, "EMBEDDING_SERVER_INTERNAL_TOKEN"),
+            artifact_url=artifact_url,
+            adapter_url=adapter_url,
+            adapter_token=environment.get("EMBEDDING_ADAPTER_TOKEN", "").strip()
+            or None,
+            deployment_key=environment.get("EMBEDDING_DEPLOYMENT_KEY", "").strip()
+            or None,
+            deployment_alias=required(environment, "EMBEDDING_DEPLOYMENT_ALIAS"),
+            model=required(environment, "EMBEDDING_MODEL"),
+            version=required(environment, "EMBEDDING_MODEL_VERSION"),
+            dimensions=required_positive_int(environment, "EMBEDDING_DIMENSIONS"),
+            normalized=boolean(environment, "EMBEDDING_NORMALIZED", True),
+            capabilities=required_capabilities(
+                tuple(
+                    sorted(
+                        {
+                            item.strip()
+                            for item in environment.get(
+                                "EMBEDDING_CAPABILITIES",
+                                "embedding.text",
+                            ).split(",")
+                            if item.strip()
+                        }
+                    )
+                )
+            ),
+            max_units=positive_int(environment, "EMBEDDING_MAX_UNITS", 256),
+        )
+
+
+def required(environment: dict[str, str], key: str) -> str:
+    value = environment.get(key, "").strip()
+    if not value:
+        raise ValueError(f"缺少 {key}")
+    return value
+
+
+def positive_int(environment: dict[str, str], key: str, default: int) -> int:
+    raw = environment.get(key, str(default)).strip()
+    try:
+        value = int(raw)
+    except ValueError:
+        raise ValueError(f"{key} 必须是正整数") from None
+    if value <= 0:
+        raise ValueError(f"{key} 必须是正整数")
+    return value
+
+
+def required_positive_int(environment: dict[str, str], key: str) -> int:
+    return positive_int(environment, key, 0)
+
+
+def boolean(environment: dict[str, str], key: str, default: bool) -> bool:
+    raw = environment.get(key, str(default).lower()).strip().lower()
+    if raw not in {"true", "false"}:
+        raise ValueError(f"{key} 必须是 true 或 false")
+    return raw == "true"
+
+
+def required_capabilities(value: tuple[str, ...]) -> tuple[str, ...]:
+    if not value:
+        raise ValueError("EMBEDDING_CAPABILITIES 不能为空")
+    return value
+
+
+def validate_intranet_url(raw: str) -> None:
+    parsed = urlparse(raw)
+    if (
+        parsed.scheme not in {"http", "https"}
+        or not parsed.hostname
+        or parsed.username
+        or parsed.password
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError("Embedding 内部 URL 无效")
+    host = parsed.hostname.lower()
+    if host == "localhost" or host.endswith(".internal") or "." not in host:
+        return
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        raise ValueError("Embedding 内部 URL 必须使用本地或私网地址") from None
+    if not (address.is_private or address.is_loopback):
+        raise ValueError("Embedding 内部 URL 禁止使用公网地址")

package/template/apps/embedding-server/src/southwind_embedding_server/contracts.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+type JsonValue = (
+    str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]
+)
+
+
+def to_camel(value: str) -> str:
+    first, *rest = value.split("_")
+    return first + "".join(part.capitalize() for part in rest)
+
+
+class CanonicalModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        extra="forbid",
+    )
+
+
+class ArtifactInput(CanonicalModel):
+    value: str = Field(min_length=1)
+    media_type: str = Field(min_length=1)
+    byte_size: int = Field(ge=1)
+    sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
+
+
+class EmbeddingItem(CanonicalModel):
+    id: str = Field(min_length=1, max_length=200)
+    text: str | None = None
+    source: ArtifactInput | None = None
+
+    @model_validator(mode="after")
+    def exactly_one_input(self) -> Self:
+        if (self.text is None) == (self.source is None):
+            raise ValueError("Embedding Item 必须且只能包含一种输入")
+        if self.text is not None and not self.text.strip():
+            raise ValueError("Embedding 文本不能为空")
+        return self
+
+
+class RuntimeLimits(CanonicalModel):
+    max_duration_seconds: int = Field(ge=1, le=600)
+    max_input_bytes: int = Field(ge=1, le=268_435_456)
+    max_output_bytes: int = Field(ge=1, le=268_435_456)
+    max_units: int = Field(ge=1, le=256)
+    max_artifacts: int | None = Field(default=None, ge=1, le=16)
+    max_pixels_per_artifact: int | None = Field(
+        default=None,
+        ge=1,
+        le=100_000_000,
+    )
+
+
+class ProviderEgress(CanonicalModel):
+    mode: Literal["forbidden", "configured-endpoint"]
+    deployment_key: str | None = None
+
+
+class ProviderDataPolicy(CanonicalModel):
+    input_fields: list[dict[str, JsonValue]]
+    envelope_fields: list[dict[str, JsonValue]]
+
+
+class EmbeddingRequest(CanonicalModel):
+    kind: Literal["embedding"]
+    operation_key: str = Field(min_length=1)
+    items: list[EmbeddingItem] = Field(min_length=1, max_length=256)
+    options: JsonValue
+    input_modalities: list[Literal["text", "image"]] = Field(min_length=1)
+    required_capabilities: list[str] = Field(min_length=1, max_length=32)
+    data_classification: Literal["public", "internal", "sensitive"]
+    limits: RuntimeLimits
+    provider_egress: ProviderEgress
+    provider_data_policy: ProviderDataPolicy | None = None
+
+
+class EmbeddingVector(CanonicalModel):
+    id: str
+    vector: list[float]
+    input_sha256: str
+
+
+class EmbeddingMetadata(CanonicalModel):
+    deployment_alias: str
+    model: str
+    version: str
+    dimensions: int
+    normalized: bool
+
+
+class EmbeddingResponse(CanonicalModel):
+    batch_id: str
+    items: list[EmbeddingVector]
+    metadata: EmbeddingMetadata
+
+
+class ErrorResponse(CanonicalModel):
+    code: str
+    message: str
+    request_id: str
+    retryable: bool

package/template/apps/embedding-server/src/southwind_embedding_server/error.py

@@ -0,0 +1,6 @@
+class SafeEmbeddingError(Exception):
+    def __init__(self, code: str, message: str, retryable: bool) -> None:
+        super().__init__(message)
+        self.code = code
+        self.safe_message = message
+        self.retryable = retryable

package/template/apps/embedding-server/src/southwind_embedding_server/image_input.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+from io import BytesIO
+
+import httpx
+from PIL import Image, UnidentifiedImageError
+
+from .config import EmbeddingConfig
+from .contracts import ArtifactInput
+from .error import SafeEmbeddingError
+
+_IMAGE_TYPES = frozenset({"image/jpeg", "image/png", "image/webp"})
+
+
+async def load_image(
+    source: ArtifactInput,
+    config: EmbeddingConfig,
+    max_bytes: int,
+    max_pixels: int,
+) -> tuple[str, str]:
+    if source.media_type.lower() not in _IMAGE_TYPES:
+        raise invalid("Embedding 图片格式不受支持")
+    body = bytearray()
+    digest = hashlib.sha256()
+    try:
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(
+                config.request_timeout_seconds,
+                connect=config.connect_timeout_seconds,
+            )
+        ) as client:
+            async with client.stream(
+                "GET",
+                config.artifact_url,
+                headers={
+                    "authorization": f"Bearer {config.internal_token}",
+                    "x-ai-artifact-ref": source.value,
+                },
+            ) as response:
+                response.raise_for_status()
+                async for chunk in response.aiter_bytes():
+                    body.extend(chunk)
+                    digest.update(chunk)
+                    if len(body) > min(source.byte_size, max_bytes):
+                        raise budget("Embedding 图片超过输入上限")
+    except SafeEmbeddingError:
+        raise
+    except Exception as error:
+        raise SafeEmbeddingError(
+            "ARTIFACT_UNAVAILABLE",
+            "Embedding Runtime 无法读取图片 Artifact",
+            True,
+        ) from error
+    if len(body) != source.byte_size or digest.hexdigest() != source.sha256:
+        raise invalid("Embedding Artifact 完整性校验失败")
+    encoded = await asyncio.to_thread(sanitize, bytes(body), max_pixels)
+    return encoded, source.sha256
+
+
+def sanitize(raw: bytes, max_pixels: int) -> str:
+    try:
+        with Image.open(BytesIO(raw)) as source:
+            width, height = source.size
+            if width <= 0 or height <= 0 or width * height > max_pixels:
+                raise budget("Embedding 图片像素超过上限")
+            source.load()
+            normalized = source.convert(
+                "RGBA" if source.has_transparency_data else "RGB"
+            )
+            target = BytesIO()
+            normalized.save(target, format="PNG", optimize=False)
+    except SafeEmbeddingError:
+        raise
+    except (Image.DecompressionBombError, UnidentifiedImageError, OSError):
+        raise invalid("Embedding 图片内容损坏") from None
+    return base64.b64encode(target.getvalue()).decode()
+
+
+def invalid(message: str) -> SafeEmbeddingError:
+    return SafeEmbeddingError("INVALID_INPUT", message, False)
+
+
+def budget(message: str) -> SafeEmbeddingError:
+    return SafeEmbeddingError("BUDGET_EXCEEDED", message, False)

package/template/apps/embedding-server/tests/__init__.py

@@ -0,0 +1 @@
+