画像編集 - Vector Retrieval Service for Milvus - Alibaba Cloud ドキュメントセンター

AI_IMAGE_EDIT 関数は、テキストプロンプトに基づいて、1 つ以上の入力イメージから編集済みイメージの URL を生成します。この関数は、白抜き画像生成、背景置換、スタイル変換、参照イメージの融合に使用します。

構文

AI_IMAGE_EDIT は、REST API を介して直接呼び出すか、Milvus コレクションスキーマのコレクション関数として統合できます。

REST API

{
  "model_name": "wan2.7-image-pro",
  "texts": ["<image_url>"],
  "params": {"prompt": "<edit_instruction>", "n": 1}
}

複数イメージの入力には image_inputs を使用します。各内部配列は 1 つの編集タスクを表します。

{
  "model_name": "wan2.7-image-pro",
  "image_inputs": [["<base_image_url>", "<reference_image_url>"]],
  "params": {"prompt": "<edit_instruction>", "n": 2}
}

Python

schema = MilvusClient.create_schema(auto_id=True, enable_dynamic_field=False)
schema.add_field("id", DataType.INT64, is_primary=True)
schema.add_field("image_url", DataType.VARCHAR, max_length=4096)
schema.add_field("instruction", DataType.VARCHAR, max_length=512)
schema.add_field("edited_image", DataType.VARCHAR, max_length=8192)
schema.add_field("dummy_vector", DataType.FLOAT_VECTOR, dim=2)
schema.add_function(
    Function(
        name="edit_image",
        function_type=texttransform_function_type(),
        input_field_names=["image_url", "instruction"],
        output_field_names=["edited_image"],
        params={
            "provider": "aliyun_milvus",
            "model_name": "wan2.7-image-pro",
            "task": "ai_image_edit",
            "image_fields": "image_url",
            "prompt": "${instruction}",
            "n": "1",
            "size": "1024*1024",
            "watermark": "false",
            "timeout_sec": "180",
        },
    )
)

パラメーター

パラメーター	説明
`model_name`	必須。イメージ URL を同期的に返すモデルです。`wan2.7-image-pro` (推奨)、`wan2.7-image`、またはその他の互換性のあるモデルを使用します。
`prompt`	必須。希望する編集内容を記述します。コレクション関数のスキーマでは、`${field_name}` を使用して他の入力フィールドを参照します。
`texts`	単一イメージ入力用のイメージ URL の配列です。各要素は 1 つの編集タスクを表します。`image_inputs` と同時に使用することはできません。
`image_inputs`	複数イメージ入力用の 2 次元配列です。各内部配列には 1 つのタスクのイメージが含まれます。同じリクエスト内では、タスクごとのイメージ数が一貫している必要があります。
`image_fields`	コレクション関数のみ。オプション。イメージフィールドを指定します。デフォルトは最初の入力フィールドです。`base_image,reference_image` のようなコンマ区切りの文字列、または JSON 文字列配列を受け入れます。
`n`	オプション。デフォルト: `1`。有効な値: 1～6。`n=1` の場合、単一のイメージ URL が返されます。`n > 1` の場合、イメージ URL のリストが返され、コレクション関数の出力フィールドは `VARCHAR` 型ではなく `JSON` 型を使用する必要があります。
`size` / `negative_prompt` / `seed` / `bbox_list` / `watermark`	オプション。モデルの機能に基づいてモデルに渡されます。
`timeout_sec` / `max_concurrency`	オプション。それぞれリクエストごとのタイムアウトとバッチ同時実行数を制御します。
`provider` / `task`	コレクション関数でのみ必須です。`provider` を `aliyun_milvus` に、`task` を `ai_image_edit` に設定します。

戻り値

n=1 の場合、data.output.outputs の各要素はイメージ URL です。n > 1 の場合、各要素は images 配列を含む JSON 文字列です。data.usage には image_tokens と total_tokens が含まれる場合があります。

例 1：単一イメージの背景置換 (texts, n=1)

主な被写体を維持したまま、人とペットの写真の背景を白一色のクリーンな背景に置き換えます。デフォルトのアセットは、人と犬の写真です。curl の例では jq が必要です。

REST API

#!/usr/bin/env bash
set -euo pipefail

MILVUS_REST_BASE_URL="http://c-xxxx.milvus.aliyuncs.com:19530"
MILVUS_AUTH_TOKEN="<yourUsername>:<yourPassword>"

post_json() {
  local path="$1"
  local body="$2"
  curl -X POST \
    "$MILVUS_REST_BASE_URL$path" \
    -H "Authorization: Bearer $MILVUS_AUTH_TOKEN" \
    -H "Content-Type: application/json" \
    -d "$body"
}

BODY=$(cat <<JSON
{
  "model_name": "wan2.7-image-pro",
  "texts": ["https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"],
  "params": {
    "prompt": "Keep the main subject and replace the background with a clean white background.",
    "n": 1,
    "size": "1024*1024",
    "watermark": false,
    "timeout_sec": 180
  }
}
JSON
)
RESPONSE_BODY="$(post_json "/v2/vectordb/ai/image_edit" "$BODY")"
if command -v jq >/dev/null 2>&1; then
  echo "$RESPONSE_BODY" | jq .
  [ "$(echo "$RESPONSE_BODY" | jq -r '.code // -1')" = "0" ] || exit 1
else
  echo "$RESPONSE_BODY"
fi

Python

from __future__ import annotations

from typing import Any

from pymilvus import DataType, Function, FunctionType, MilvusClient

MILVUS_URI = "http://c-xxxx.milvus.aliyuncs.com:19530"
MILVUS_TOKEN = "<yourUsername>:<yourPassword>"

DUMMY_VECTOR_DIM = 2
TEXTTRANSFORM_FUNCTION_TYPE = 9

def texttransform_function_type() -> Any:
    for type_name in ("TEXTTRANSFORM", "TEXT_TRANSFORM", "TextTransform"):
        function_type = getattr(FunctionType, type_name, None)
        if function_type is not None:
            return function_type
    # Alibaba Cloud Milvus は、ホストされた拡張機能 (関数型値 9) として TEXTTRANSFORM を提供します。
    # 一部の pymilvus バージョンにはこの列挙型メンバーが組み込まれていませんが、Function(...) は FunctionType(...) を介して検証します。
    existing = getattr(FunctionType, "_value2member_map_", {}).get(TEXTTRANSFORM_FUNCTION_TYPE)
    if existing is not None:
        return existing
    extension = int.__new__(FunctionType, TEXTTRANSFORM_FUNCTION_TYPE)
    extension._name_ = "TEXTTRANSFORM"
    extension._value_ = TEXTTRANSFORM_FUNCTION_TYPE
    FunctionType._value2member_map_[TEXTTRANSFORM_FUNCTION_TYPE] = extension
    FunctionType._member_map_["TEXTTRANSFORM"] = extension
    return extension

def add_id(schema: Any) -> None:
    schema.add_field("id", DataType.INT64, is_primary=True)

def add_dummy_vector(schema: Any) -> None:
    schema.add_field("dummy_vector", DataType.FLOAT_VECTOR, dim=DUMMY_VECTOR_DIM)

def run_texttransform_example(*, client, collection_name, input_fields, output_field, function_name, function_params, rows) -> None:
    if client.has_collection(collection_name):
        client.drop_collection(collection_name)
    schema = MilvusClient.create_schema(auto_id=True, enable_dynamic_field=False)
    add_id(schema)
    for name, data_type, max_length in input_fields:
        field_params = {"max_length": max_length} if max_length is not None else {}
        schema.add_field(name, data_type, **field_params)
    output_name, output_data_type, output_max_length = output_field
    output_params = {"max_length": output_max_length} if output_max_length is not None else {}
    schema.add_field(output_name, output_data_type, **output_params)
    add_dummy_vector(schema)
    schema.add_function(
        Function(
            name=function_name,
            function_type=texttransform_function_type(),
            input_field_names=[name for name, _, _ in input_fields],
            output_field_names=[output_name],
            params=function_params,
        )
    )
    index_params = client.prepare_index_params()
    index_params.add_index(field_name="dummy_vector", index_type="AUTOINDEX", metric_type="COSINE")
    client.create_collection(collection_name=collection_name, schema=schema, index_params=index_params)
    client.insert(collection_name, rows)
    client.flush(collection_name)
    fields = [name for name, _, _ in input_fields] + [output_name]
    for row in client.query(collection_name, filter="", output_fields=fields, limit=len(rows)):
        print(row)

MODEL_NAME = "wan2.7-image-pro"
client = MilvusClient(uri=MILVUS_URI, token=MILVUS_TOKEN)

run_texttransform_example(
    client=client,
    collection_name="simple_ai_image_edit_schema",
    input_fields=[("image_url", DataType.VARCHAR, 4096), ("instruction", DataType.VARCHAR, 512)],
    output_field=("edited_image", DataType.VARCHAR, 8192),
    function_name="edit_image",
    function_params={"provider": "aliyun_milvus", "model_name": MODEL_NAME, "task": "ai_image_edit", "image_fields": "image_url", "prompt": "${instruction}", "n": "1", "size": "1024*1024", "watermark": "false", "timeout_sec": "180"},
    rows=[{"image_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg", "instruction": "Keep the main subject and replace the background with a clean white background.", "dummy_vector": [0.1, 0.2]}],
)

期待される結果：data.output.outputs[0] は、edited_image フィールド (VARCHAR) に格納される空ではない編集済みイメージ URL です。生成されるイメージは非決定的であり、固定の視覚的出力に対してアサーションを行うべきではありません。

例 2：人とペットの写真と服の参照からブランドコンセプトイメージを生成

人とペットの写真を被写体の参照として、服の素材を色と質感の参照として使用し、1 回のリクエストで 2 つのソーシャルメディア用コンセプトイメージを生成して手動レビューを行います。

REST API

#!/usr/bin/env bash
set -euo pipefail

MILVUS_REST_BASE_URL="http://c-xxxx.milvus.aliyuncs.com:19530"
MILVUS_AUTH_TOKEN="<yourUsername>:<yourPassword>"

post_json() {
  local path="$1"
  local body="$2"
  curl -X POST \
    "$MILVUS_REST_BASE_URL$path" \
    -H "Authorization: Bearer $MILVUS_AUTH_TOKEN" \
    -H "Content-Type: application/json" \
    -d "$body"
}

BODY=$(cat <<JSON
{
  "model_name": "wan2.7-image-pro",
  "image_inputs": [["https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260415/hynnff/wan-video-edit-clothes.webp"]],
  "params": {
    "prompt": "1 枚目の画像の人物、犬、海辺の構図を維持し、2 枚目の画像は服の色と質感の参考としてのみ使用して、ブランドセーフなソーシャルメディアのコンセプト画像を生成します。",
    "n": 2,
    "size": "1024*1024",
    "watermark": false,
    "timeout_sec": 180
  }
}
JSON
)
RESPONSE_BODY="$(post_json "/v2/vectordb/ai/image_edit" "$BODY")"
if command -v jq >/dev/null 2>&1; then
  echo "$RESPONSE_BODY" | jq .
  [ "$(echo "$RESPONSE_BODY" | jq -r '.code // -1')" = "0" ] || exit 1
else
  echo "$RESPONSE_BODY"
fi

Python

from __future__ import annotations

from typing import Any

from pymilvus import DataType, Function, FunctionType, MilvusClient

MILVUS_URI = "http://c-xxxx.milvus.aliyuncs.com:19530"
MILVUS_TOKEN = "<yourUsername>:<yourPassword>"

DUMMY_VECTOR_DIM = 2
TEXTTRANSFORM_FUNCTION_TYPE = 9

def texttransform_function_type() -> Any:
    for type_name in ("TEXTTRANSFORM", "TEXT_TRANSFORM", "TextTransform"):
        function_type = getattr(FunctionType, type_name, None)
        if function_type is not None:
            return function_type
    # Alibaba Cloud Milvus は、ホストされた拡張機能 (関数型値 9) として TEXTTRANSFORM を提供します。
    # 一部の pymilvus バージョンにはこの列挙型メンバーが組み込まれていませんが、Function(...) は FunctionType(...) を介して検証します。
    existing = getattr(FunctionType, "_value2member_map_", {}).get(TEXTTRANSFORM_FUNCTION_TYPE)
    if existing is not None:
        return existing
    extension = int.__new__(FunctionType, TEXTTRANSFORM_FUNCTION_TYPE)
    extension._name_ = "TEXTTRANSFORM"
    extension._value_ = TEXTTRANSFORM_FUNCTION_TYPE
    FunctionType._value2member_map_[TEXTTRANSFORM_FUNCTION_TYPE] = extension
    FunctionType._member_map_["TEXTTRANSFORM"] = extension
    return extension

def add_id(schema: Any) -> None:
    schema.add_field("id", DataType.INT64, is_primary=True)

def add_dummy_vector(schema: Any) -> None:
    schema.add_field("dummy_vector", DataType.FLOAT_VECTOR, dim=DUMMY_VECTOR_DIM)

def run_texttransform_example(*, client, collection_name, input_fields, output_field, function_name, function_params, rows) -> None:
    if client.has_collection(collection_name):
        client.drop_collection(collection_name)
    schema = MilvusClient.create_schema(auto_id=True, enable_dynamic_field=False)
    add_id(schema)
    for name, data_type, max_length in input_fields:
        field_params = {"max_length": max_length} if max_length is not None else {}
        schema.add_field(name, data_type, **field_params)
    output_name, output_data_type, output_max_length = output_field
    output_params = {"max_length": output_max_length} if output_max_length is not None else {}
    schema.add_field(output_name, output_data_type, **output_params)
    add_dummy_vector(schema)
    schema.add_function(
        Function(
            name=function_name,
            function_type=texttransform_function_type(),
            input_field_names=[name for name, _, _ in input_fields],
            output_field_names=[output_name],
            params=function_params,
        )
    )
    index_params = client.prepare_index_params()
    index_params.add_index(field_name="dummy_vector", index_type="AUTOINDEX", metric_type="COSINE")
    client.create_collection(collection_name=collection_name, schema=schema, index_params=index_params)
    client.insert(collection_name, rows)
    client.flush(collection_name)
    fields = [name for name, _, _ in input_fields] + [output_name]
    for row in client.query(collection_name, filter="", output_fields=fields, limit=len(rows)):
        print(row)

MODEL_NAME = "wan2.7-image-pro"
client = MilvusClient(uri=MILVUS_URI, token=MILVUS_TOKEN)

# image_inputs の各項目には、ベースイメージと参照イメージが含まれます。n=2 は 2 つの候補結果を返します。
# 注：ai_image_edit では、n > 1 の場合、出力フィールドは DataType.JSON である必要があります (VARCHAR はサポートされていません)。
run_texttransform_example(
    client=client,
    collection_name="simple_ai_image_edit_multi_schema",
    input_fields=[
        ("base_image_url", DataType.VARCHAR, 4096),
        ("reference_image_url", DataType.VARCHAR, 4096),
        ("instruction", DataType.VARCHAR, 1024),
    ],
    output_field=("edited_images", DataType.JSON, None),
    function_name="edit_images_with_reference",
    function_params={
        "provider": "aliyun_milvus",
        "model_name": MODEL_NAME,
        "task": "ai_image_edit",
        "image_fields": '["base_image_url","reference_image_url"]',
        "prompt": "${instruction}",
        "n": "2",
        "size": "1024*1024",
        "watermark": "false",
        "timeout_sec": "180",
    },
    rows=[
        {
            "base_image_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg",
            "reference_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/20260415/hynnff/wan-video-edit-clothes.webp",
            "instruction": "Keep the person, dog, and seaside composition from the base image. Use the reference image only as clothing color and texture guidance. Generate brand-safe social media concept images.",
            "dummy_vector": [0.1, 0.2],
        }
    ],
)

期待される結果：n=2 のため、data.output.outputs[0] は、2 つの空ではないイメージ URL を含む images 配列を持つ JSON 文字列です。

重要

ai_image_edit タスクで n > 1 の場合、コレクション関数の出力フィールドは VARCHAR 型ではなく JSON 型を使用する必要があります。そうしないと、コレクションの作成は output field must be a JSON field for task [ai_image_edit] when n > 1 というエラーで失敗します。