Xây dựng Plugin nhà cung cấp tạo hình ảnh

Các plugin của nhà cung cấp gen hình ảnh đăng ký một chương trình phụ trợ phục vụ mọi lệnh gọi công cụ image_generate — DALL·E, gpt-image, Grok, Flux, Imagen, Stable Diffusion, fal, Replicate, giàn ComfyUI cục bộ, bất cứ thứ gì. Các nhà cung cấp tích hợp (OpenAI, OpenAI-Codex, xAI) đều được cung cấp dưới dạng plugin. Bạn có thể thêm một cái mới hoặc ghi đè một cái được đóng gói bằng cách thả một thư mục vào plugins/image_gen/<name>/.

:::mẹo Image-gen là một trong số plugin phụ trợ được Hermes hỗ trợ. Các plugin khác (với các ABC chuyên biệt hơn) là Plugin nhà cung cấp bộ nhớ, Plugin công cụ bối cảnh và Plugin nhà cung cấp mô hình. Các plugin công cụ/hook/CLI chung có trong Xây dựng plugin Hermes. :::

Cách hoạt động của tính năng khám phá

Hermes quét các phần phụ trợ của gen hình ảnh ở ba nơi:

1. Theo gói — <repo>/plugins/image_gen/<name>/ (được tải tự động với kind: backend, luôn có sẵn)
2. Người dùng — ~/.hermes/plugins/image_gen/<name>/ (chọn tham gia thông qua plugins.enabled)
3. Pip — các gói khai báo điểm vào hermes_agent.plugins

Hàm register(ctx) của mỗi plugin gọi ctx.register_image_gen_provider(...) — để đưa nó vào sổ đăng ký trong agent/image_gen_registry.py. Nhà cung cấp đang hoạt động được chọn bởi image_gen.provider trong config.yaml; công cụ hermes hướng dẫn người dùng thực hiện việc lựa chọn.

Trình bao bọc công cụ image_generate yêu cầu cơ quan đăng ký tìm nhà cung cấp đang hoạt động và gửi đến đó. Nếu không có nhà cung cấp nào được đăng ký, công cụ sẽ hiển thị một lỗi hữu ích khi trỏ vào công cụ hermes.

Cấu trúc thư mục

plugins/image_gen/my-backend/
├── __init__.py      # ImageGenProvider subclass + register()
└── plugin.yaml      # Manifest with kind: backend

Một plugin đi kèm đã hoàn tất vào thời điểm này. Cần phải thêm plugin người dùng tại ~/.hermes/plugins/image_gen/<name>/ vào plugins.enabled trong config.yaml (hoặc chạy hermes plugin kích hoạt <name>).

Nhà cung cấp ImageGen ABC

Lớp con agent.image_gen_provider.ImageGenProvider. Các thành viên bắt buộc duy nhất là thuộc tính name và phương thức generate() — mọi thứ khác đều có giá trị mặc định hợp lý:

# plugins/image_gen/my-backend/__init__.py
from typing import Any, Dict, List, Optional
import os

from agent.image_gen_provider import (
    DEFAULT_ASPECT_RATIO,
    ImageGenProvider,
    error_response,
    resolve_aspect_ratio,
    save_b64_image,
    success_response,
)


class MyBackendImageGenProvider(ImageGenProvider):
    @property
    def name(self) -> str:
        # Stable id used in image_gen.provider config. Lowercase, no spaces.
        return "my-backend"

    @property
    def display_name(self) -> str:
        # Human label shown in `hermes tools`. Defaults to name.title() if omitted.
        return "My Backend"

    def is_available(self) -> bool:
        # Return False if credentials or deps are missing.
        # The tool's availability gate calls this before dispatch.
        if not os.environ.get("MY_BACKEND_API_KEY"):
            return False
        try:
            import my_backend_sdk  # noqa: F401
        except ImportError:
            return False
        return True

    def list_models(self) -> List[Dict[str, Any]]:
        # Catalog shown in `hermes tools` model picker.
        return [
            {
                "id": "my-model-fast",
                "display": "My Model (Fast)",
                "speed": "~5s",
                "strengths": "Quick iteration",
                "price": "$0.01/image",
            },
            {
                "id": "my-model-hq",
                "display": "My Model (HQ)",
                "speed": "~30s",
                "strengths": "Highest fidelity",
                "price": "$0.04/image",
            },
        ]

    def default_model(self) -> Optional[str]:
        return "my-model-fast"

    def get_setup_schema(self) -> Dict[str, Any]:
        # Metadata for the `hermes tools` picker — keys to prompt for at setup.
        return {
            "name": "My Backend",
            "badge": "paid",        # optional; shown as a short tag in the picker
            "tag": "One-line description shown under the name",
            "env_vars": [
                {
                    "key": "MY_BACKEND_API_KEY",
                    "prompt": "My Backend API key",
                    "url": "https://my-backend.example.com/api-keys",
                },
            ],
        }

    def generate(
        self,
        prompt: str,
        aspect_ratio: str = DEFAULT_ASPECT_RATIO,
        **kwargs: Any,
    ) -> Dict[str, Any]:
        prompt = (prompt or "").strip()
        aspect_ratio = resolve_aspect_ratio(aspect_ratio)

        if not prompt:
            return error_response(
                error="Prompt is required",
                error_type="invalid_input",
                provider=self.name,
                prompt="",
                aspect_ratio=aspect_ratio,
            )

        # Model selection precedence: env var → config → default. The helper
        # _resolve_model() in the built-in openai plugin is a good reference.
        model_id = kwargs.get("model") or self.default_model() or "my-model-fast"

        try:
            import my_backend_sdk
            client = my_backend_sdk.Client(api_key=os.environ["MY_BACKEND_API_KEY"])
            result = client.generate(
                prompt=prompt,
                model=model_id,
                aspect_ratio=aspect_ratio,
            )

            # Two shapes supported:
            #   - URL string: return it as `image`
            #   - base64 data: save under $HERMES_HOME/cache/images/ via save_b64_image()
            if result.get("image_b64"):
                path = save_b64_image(
                    result["image_b64"],
                    prefix=self.name,
                    extension="png",
                )
                image = str(path)
            else:
                image = result["image_url"]

            return success_response(
                image=image,
                model=model_id,
                prompt=prompt,
                aspect_ratio=aspect_ratio,
                provider=self.name,
            )
        except Exception as exc:
            return error_response(
                error=str(exc),
                error_type=type(exc).__name__,
                provider=self.name,
                model=model_id,
                prompt=prompt,
                aspect_ratio=aspect_ratio,
            )

đăng ký def (ctx) -> Không có:
    """Điểm vào plugin — được gọi một lần khi tải."""
    ctx.register_image_gen_provider(MyBackendImageGenProvider())

plugin.yaml

name: my-backend
version: 1.0.0
description: My image backend — text-to-image via My Backend SDK
author: Your Name
kind: backend
requires_env:
  - MY_BACKEND_API_KEY

kind: backend là định tuyến plugin đến đường dẫn đăng ký image-gen. requires_env được nhắc trong quá trình cài đặt plugin hermes.

Tài liệu tham khảo ABC

Hợp đồng đầy đủ trong agent/image_gen_provider.py. Các phương pháp bạn thường ghi đè:

Member	Required	Default	Purpose
name	✅	—	Stable id used in image_gen.provider config
display_name	—	name.title()	Label shown in hermes tools
is_available()	—	True	Gate for missing creds/deps
list_models()	—	[]	Catalog for hermes tools model picker
default_model()	—	first from list_models()	Fallback when no model is configured
get_setup_schema()	—	minimal	Picker metadata + env-var prompts
generate(prompt, aspect_ratio, **kwargs)	✅	—	The call

Định dạng phản hồi

generate() phải trả về một lệnh được tạo thông qua success_response() hoặc error_response(). Cả hai đều tồn tại trong agent/image_gen_provider.py.

Success:

success_response(
    image=<url-or-absolute-path>,
    model=<model-id>,
    prompt=<echoed-prompt>,
    aspect_ratio="landscape" | "square" | "portrait",
    provider=<your-provider-name>,
    extra={...},  # optional backend-specific fields
)

Error:

error_response(
    error="human-readable message",
    error_type="provider_error" | "invalid_input" | "<exception class name>",
    provider=<your-provider-name>,
    model=<model-id>,
    prompt=<prompt>,
    aspect_ratio=<resolved aspect>,
)

Trình bao bọc công cụ JSON tuần tự hóa lệnh và chuyển nó cho LLM. Lỗi được hiển thị dưới dạng kết quả của công cụ; LLM quyết định cách giải thích chúng cho người dùng.

Xử lý đầu ra base64 và URL

Một số chương trình phụ trợ trả về URL hình ảnh (fal, Replica); những người khác trả về tải trọng base64 (OpenAI gpt-image-2). Đối với trường hợp base64, hãy sử dụng save_b64_image() — nó ghi vào $HERMES_HOME/cache/images/<prefix>_<timestamp>_<uuid>.<ext> và trả về Path tuyệt đối. Truyền đường dẫn đó (dưới dạng str) dưới dạng image= trong success_response(). Phân phối qua cổng (bong bóng ảnh Telegram, tệp đính kèm Discord) nhận dạng cả URL và đường dẫn tuyệt đối.

Ghi đè của người dùng

Thả một plugin người dùng tại ~/.hermes/plugins/image_gen/<name>/ với cùng thuộc tính name như một gói được đóng gói và kích hoạt nó thông qua hermes plugin kích hoạt <name> — sổ đăng ký là người viết cuối cùng-thắng, vì vậy phiên bản của bạn sẽ thay thế phiên bản tích hợp sẵn. Hữu ích khi trỏ plugin openai vào proxy riêng hoặc trao đổi trong danh mục mô hình tùy chỉnh.

##Thử nghiệm

export HERMES_HOME=/tmp/hermes-imggen-test
mkdir -p $HERMES_HOME/plugins/image_gen/my-backend
# …copy __init__.py + plugin.yaml into that dir…

export MY_BACKEND_API_KEY=your-test-key
hermes plugins enable my-backend

# Pick it as the active provider
echo "image_gen:" >> $HERMES_HOME/config.yaml
echo "  provider: my-backend" >> $HERMES_HOME/config.yaml

# Luyện tập nó
hermes -z "Tạo hình ảnh một chú chó corgi trong bộ đồ du hành vũ trụ"

Hoặc tương tác: hermes tools → "Image Generation" → chọn my-backend → nhập khóa API nếu được nhắc.

Triển khai tham khảo

• plugins/image_gen/openai/__init__.py — gpt-image-2 ở các cấp thấp/trung bình/cao dưới dạng ba ID mô hình ảo chia sẻ một mô hình API với các thông số chất lượng khác nhau. Ví dụ điển hình về các mô hình theo cấp bậc trong một chuỗi ưu tiên phụ trợ + config.yaml.
• plugins/image_gen/xai/__init__.py — Grok Imagine qua xAI. Hình dạng khác nhau (đầu ra URL, danh mục đơn giản hơn).
• plugins/image_gen/openai-codex/__init__.py — Biến thể API phản hồi kiểu Codex sử dụng lại SDK OpenAI với URL cơ sở định tuyến khác.

Phân phối qua pip

# pyproject.toml
[project.entry-points."hermes_agent.plugins"]
my-backend-imggen = "my_backend_imggen_package"

my_backend_imggen_package phải hiển thị hàm register cấp cao nhất. Xem Phân phối qua pip trong hướng dẫn chung về plugin để biết cách thiết lập đầy đủ.

Các trang liên quan

• Tạo hình ảnh — tài liệu về tính năng hướng tới người dùng
• Tổng quan về plugin — tổng quan về tất cả các loại plugin
• Xây dựng Plugin Hermes — hướng dẫn sử dụng các công cụ/hook/dấu gạch chéo chung