Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

feat(api): add image_update_mode for chunk image updates (#18889)

Sourav Rajvib15b159d079f
diff --git a/api/apps/restful_apis/chunk_api.py b/api/apps/restful_apis/chunk_api.py
index 60f512767e..93498757ce 100644
--- a/api/apps/restful_apis/chunk_api.py
+++ b/api/apps/restful_apis/chunk_api.py
@@ -49,7 +49,12 @@ from api.utils.api_utils import (
get_result,
server_error_response,
)
-from api.utils.image_utils import store_chunk_image
+from api.utils.image_utils import (
+ IMAGE_UPDATE_MODE_REMOVE,
+ IMAGE_UPDATE_MODES,
+ remove_chunk_image,
+ store_chunk_image,
+)
from api.utils.pagination_utils import DEFAULT_PAGE, DEFAULT_PAGE_SIZE, validate_rest_api_ids, validate_rest_api_page, validate_rest_api_page_size
from api.utils.reference_metadata_utils import (
enrich_chunks_with_document_metadata,
@@ -91,19 +96,45 @@ def _decode_chunk_image_base64(image_base64):
return image_binary, None
-def _store_chunk_image_or_error(dataset_id, chunk_id, image_binary):
+def _parse_image_update_mode(req):
+ if "image_update_mode" not in req:
+ return "append", None
+ mode = req.get("image_update_mode")
+ if not isinstance(mode, str):
+ return None, "`image_update_mode` must be a string"
+ mode = mode.strip().lower()
+ if mode not in IMAGE_UPDATE_MODES:
+ return None, "`image_update_mode` must be one of: append, replace, remove"
+ return mode, None
+
+
+def _store_chunk_image_or_error(dataset_id, chunk_id, image_binary, mode="append"):
try:
- store_chunk_image(dataset_id, chunk_id, image_binary)
+ store_chunk_image(dataset_id, chunk_id, image_binary, mode=mode)
except Exception:
logging.exception(
- "Failed to store chunk image. dataset_id=%s chunk_id=%s",
+ "Failed to store chunk image. dataset_id=%s chunk_id=%s mode=%s",
dataset_id,
chunk_id,
+ mode,
)
return "Failed to store chunk image"
return None
+def _remove_chunk_image_or_error(dataset_id, chunk_id):
+ try:
+ remove_chunk_image(dataset_id, chunk_id)
+ except Exception:
+ logging.exception(
+ "Failed to remove chunk image. dataset_id=%s chunk_id=%s",
+ dataset_id,
+ chunk_id,
+ )
+ return "Failed to remove chunk image"
+ return None
+
+
class Chunk(BaseModel):
id: str = ""
content: str = ""
@@ -1363,15 +1394,26 @@ async def update_chunk(tenant_id, dataset_id, document_id, chunk_id):
d["tag_feas"] = validate_tag_features(req["tag_feas"])
except ValueError as exc:
return get_error_data_result(f"`tag_feas` {exc}")
- if "image_base64" in req:
- image_binary, image_err = _decode_chunk_image_base64(req.get("image_base64"))
- if image_err:
- return get_error_data_result(message=image_err)
- store_err = _store_chunk_image_or_error(dataset_id, chunk_id, image_binary)
- if store_err:
- return get_error_data_result(message=store_err)
- d["img_id"] = f"{dataset_id}-{chunk_id}"
- d["doc_type_kwd"] = "image"
+ remove_image_after_update = False
+ if "image_update_mode" in req or "image_base64" in req:
+ image_mode, mode_err = _parse_image_update_mode(req)
+ if mode_err:
+ return get_error_data_result(message=mode_err)
+ if image_mode == IMAGE_UPDATE_MODE_REMOVE:
+ d["img_id"] = ""
+ d["doc_type_kwd"] = "text"
+ remove_image_after_update = True
+ elif "image_base64" in req:
+ image_binary, image_err = _decode_chunk_image_base64(req.get("image_base64"))
+ if image_err:
+ return get_error_data_result(message=image_err)
+ store_err = _store_chunk_image_or_error(dataset_id, chunk_id, image_binary, image_mode)
+ if store_err:
+ return get_error_data_result(message=store_err)
+ d["img_id"] = f"{dataset_id}-{chunk_id}"
+ d["doc_type_kwd"] = "image"
+ else:
+ return get_error_data_result(message="`image_base64` is required when `image_update_mode` is `append` or `replace`")
embd_id = DocumentService.get_embd_id(document_id)
model_config = resolve_model_config(dataset_tenant_id, LLMType.EMBEDDING.value, embd_id)
@@ -1393,7 +1435,12 @@ async def update_chunk(tenant_id, dataset_id, document_id, chunk_id):
)
v = 0.1 * v[0] + 0.9 * v[1] if doc.parser_id != ParserType.QA else v[1]
d[f"q_{len(v)}_vec"] = v.tolist()
- settings.docStoreConn.update({"id": chunk_id}, d, search.index_name(dataset_tenant_id), dataset_id)
+ if not settings.docStoreConn.update({"id": chunk_id}, d, search.index_name(dataset_tenant_id), dataset_id):
+ return get_error_data_result(message="Index updating failure")
+ if remove_image_after_update:
+ remove_err = _remove_chunk_image_or_error(dataset_id, chunk_id)
+ if remove_err:
+ return get_error_data_result(message=remove_err)
return get_result()
diff --git a/api/utils/image_utils.py b/api/utils/image_utils.py
index 7b93aa4923..e5ba51aff4 100644
--- a/api/utils/image_utils.py
+++ b/api/utils/image_utils.py
@@ -20,21 +20,41 @@ from PIL import Image
from common import settings
+IMAGE_UPDATE_MODE_APPEND = "append"
+IMAGE_UPDATE_MODE_REPLACE = "replace"
+IMAGE_UPDATE_MODE_REMOVE = "remove"
+IMAGE_UPDATE_MODES = frozenset(
+ {
+ IMAGE_UPDATE_MODE_APPEND,
+ IMAGE_UPDATE_MODE_REPLACE,
+ IMAGE_UPDATE_MODE_REMOVE,
+ }
+)
-def store_chunk_image(bucket, name, image_binary):
- if settings.STORAGE_IMPL.obj_exist(bucket, name):
- old_binary = settings.STORAGE_IMPL.get(bucket, name)
- old_img = Image.open(BytesIO(old_binary))
- new_img = Image.open(BytesIO(image_binary))
- old_img = old_img.convert("RGB")
- new_img = new_img.convert("RGB")
- width = max(old_img.width, new_img.width)
- height = old_img.height + new_img.height
- combined = Image.new("RGB", (width, height), (255, 255, 255))
- combined.paste(old_img, (0, 0))
- combined.paste(new_img, (0, old_img.height))
- buf = BytesIO()
- combined.save(buf, format="JPEG")
- settings.STORAGE_IMPL.put(bucket, name, buf.getvalue())
- else:
+
+def store_chunk_image(bucket, name, image_binary, mode=IMAGE_UPDATE_MODE_APPEND):
+ if mode not in (IMAGE_UPDATE_MODE_APPEND, IMAGE_UPDATE_MODE_REPLACE):
+ raise ValueError(f"unsupported image update mode for store: {mode}")
+
+ if mode == IMAGE_UPDATE_MODE_REPLACE or not settings.STORAGE_IMPL.obj_exist(bucket, name):
settings.STORAGE_IMPL.put(bucket, name, image_binary)
+ return
+
+ old_binary = settings.STORAGE_IMPL.get(bucket, name)
+ old_img = Image.open(BytesIO(old_binary))
+ new_img = Image.open(BytesIO(image_binary))
+ old_img = old_img.convert("RGB")
+ new_img = new_img.convert("RGB")
+ width = max(old_img.width, new_img.width)
+ height = old_img.height + new_img.height
+ combined = Image.new("RGB", (width, height), (255, 255, 255))
+ combined.paste(old_img, (0, 0))
+ combined.paste(new_img, (0, old_img.height))
+ buf = BytesIO()
+ combined.save(buf, format="JPEG")
+ settings.STORAGE_IMPL.put(bucket, name, buf.getvalue())
+
+
+def remove_chunk_image(bucket, name):
+ if settings.STORAGE_IMPL.obj_exist(bucket, name):
+ settings.STORAGE_IMPL.rm(bucket, name)
diff --git a/test/testcases/test_web_api/test_chunk_app/test_chunk_routes_unit.py b/test/testcases/test_web_api/test_chunk_app/test_chunk_routes_unit.py
index 7ecbbd32a9..c529879da5 100644
--- a/test/testcases/test_web_api/test_chunk_app/test_chunk_routes_unit.py
+++ b/test/testcases/test_web_api/test_chunk_app/test_chunk_routes_unit.py
@@ -327,6 +327,9 @@ def _load_chunk_module(monkeypatch):
image_utils_mod = ModuleType("api.utils.image_utils")
image_utils_mod.store_chunk_image = lambda *_args, **_kwargs: None
+ image_utils_mod.remove_chunk_image = lambda *_args, **_kwargs: None
+ image_utils_mod.IMAGE_UPDATE_MODE_REMOVE = "remove"
+ image_utils_mod.IMAGE_UPDATE_MODES = frozenset({"append", "replace", "remove"})
monkeypatch.setitem(sys.modules, "api.utils.image_utils", image_utils_mod)
services_pkg = ModuleType("api.db.services")
@@ -848,3 +851,113 @@ def test_restful_add_chunk_valid_image_base64_stores_before_insert(monkeypatch):
assert inserted.get("img_id"), inserted
assert inserted.get("doc_type_kwd") == "image", inserted
assert res["data"]["chunk"]["doc_type_kwd"] == "image", res
+
+
+def test_restful_update_chunk_replace_image_mode(monkeypatch):
+ module = _load_chunk_api_module(monkeypatch)
+ module.settings.docStoreConn.chunk = {
+ "id": "chunk-1",
+ "doc_id": "doc-1",
+ "content_with_weight": "chunk",
+ "img_id": "kb-1-chunk-1",
+ }
+ store_calls = []
+ module.store_chunk_image = lambda bucket, name, binary, mode="append": store_calls.append((bucket, name, mode))
+
+ valid_b64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
+ monkeypatch.setattr(
+ module,
+ "get_request_json",
+ lambda: _AwaitableValue({"image_base64": valid_b64, "image_update_mode": "replace"}),
+ )
+ res = _run(_route_core(module.update_chunk)("tenant-1", "kb-1", "doc-1", "chunk-1"))
+ assert res["code"] == 0, res
+ assert store_calls == [("kb-1", "chunk-1", "replace")], store_calls
+ updated = module.settings.docStoreConn.updated[-1][1]
+ assert updated["img_id"] == "kb-1-chunk-1", updated
+ assert updated["doc_type_kwd"] == "image", updated
+
+
+def test_restful_update_chunk_remove_image_mode(monkeypatch):
+ module = _load_chunk_api_module(monkeypatch)
+ module.settings.docStoreConn.chunk = {
+ "id": "chunk-1",
+ "doc_id": "doc-1",
+ "content_with_weight": "chunk",
+ "img_id": "kb-1-chunk-1",
+ }
+ call_order = []
+ original_update = module.settings.docStoreConn.update
+
+ def tracked_update(*args, **kwargs):
+ call_order.append("update")
+ return original_update(*args, **kwargs)
+
+ module.settings.docStoreConn.update = tracked_update
+ module.remove_chunk_image = lambda bucket, name: call_order.append(("remove", bucket, name))
+
+ monkeypatch.setattr(module, "get_request_json", lambda: _AwaitableValue({"image_update_mode": "remove"}))
+ res = _run(_route_core(module.update_chunk)("tenant-1", "kb-1", "doc-1", "chunk-1"))
+ assert res["code"] == 0, res
+ assert call_order == ["update", ("remove", "kb-1", "chunk-1")], call_order
+ updated = module.settings.docStoreConn.updated[-1][1]
+ assert updated["img_id"] == "", updated
+ assert updated["doc_type_kwd"] == "text", updated
+
+
+def test_restful_update_chunk_remove_image_skips_delete_when_encode_fails(monkeypatch):
+ module = _load_chunk_api_module(monkeypatch)
+ module.settings.docStoreConn.chunk = {
+ "id": "chunk-1",
+ "doc_id": "doc-1",
+ "content_with_weight": "chunk",
+ "img_id": "kb-1-chunk-1",
+ }
+ remove_calls = []
+
+ class _FailingLLMBundle(_DummyLLMBundle):
+ def encode(self, _inputs):
+ raise RuntimeError("embedding failed")
+
+ module.TenantLLMService.model_instance = staticmethod(lambda _model_config: _FailingLLMBundle())
+ module.remove_chunk_image = lambda bucket, name: remove_calls.append((bucket, name))
+
+ monkeypatch.setattr(module, "get_request_json", lambda: _AwaitableValue({"image_update_mode": "remove"}))
+ with pytest.raises(RuntimeError, match="embedding failed"):
+ _run(_route_core(module.update_chunk)("tenant-1", "kb-1", "doc-1", "chunk-1"))
+ assert remove_calls == [], remove_calls
+ assert module.settings.docStoreConn.updated == [], module.settings.docStoreConn.updated
+
+
+def test_restful_update_chunk_remove_image_skips_delete_when_update_fails(monkeypatch):
+ module = _load_chunk_api_module(monkeypatch)
+ module.settings.docStoreConn.chunk = {
+ "id": "chunk-1",
+ "doc_id": "doc-1",
+ "content_with_weight": "chunk",
+ "img_id": "kb-1-chunk-1",
+ }
+ remove_calls = []
+ module.settings.docStoreConn.update = lambda *_args, **_kwargs: False
+ module.remove_chunk_image = lambda bucket, name: remove_calls.append((bucket, name))
+
+ monkeypatch.setattr(module, "get_request_json", lambda: _AwaitableValue({"image_update_mode": "remove"}))
+ res = _run(_route_core(module.update_chunk)("tenant-1", "kb-1", "doc-1", "chunk-1"))
+ assert res["code"] == module.RetCode.DATA_ERROR, res
+ assert "Index updating failure" in res["message"], res
+ assert remove_calls == [], remove_calls
+
+
+def test_restful_update_chunk_replace_requires_image_base64(monkeypatch):
+ module = _load_chunk_api_module(monkeypatch)
+ module.settings.docStoreConn.chunk = {"id": "chunk-1", "doc_id": "doc-1", "content_with_weight": "chunk"}
+ monkeypatch.setattr(module, "get_request_json", lambda: _AwaitableValue({"image_update_mode": "replace"}))
+ res = _run(_route_core(module.update_chunk)("tenant-1", "kb-1", "doc-1", "chunk-1"))
+ assert res["code"] == module.RetCode.DATA_ERROR, res
+ assert "`image_base64` is required" in res["message"], res
+ assert module.settings.docStoreConn.updated == [], res
diff --git a/test/unit_test/api/utils/test_image_utils.py b/test/unit_test/api/utils/test_image_utils.py
new file mode 100644
index 0000000000..1c2cb15e2e
--- /dev/null
+++ b/test/unit_test/api/utils/test_image_utils.py
@@ -0,0 +1,98 @@
+#
+# Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from io import BytesIO
+from types import SimpleNamespace
+
+import pytest
+from PIL import Image
+
+from api.utils import image_utils
+
+
+def _png_bytes(width, height, color):
+ image = Image.new("RGB", (width, height), color)
+ buf = BytesIO()
+ image.save(buf, format="PNG")
+ return buf.getvalue()
+
+
+class _FakeStorage:
+ def __init__(self, existing=None):
+ self.objects = dict(existing or {})
+ self.removed = []
+
+ def obj_exist(self, bucket, name):
+ return (bucket, name) in self.objects
+
+ def get(self, bucket, name):
+ return self.objects[(bucket, name)]
+
+ def put(self, bucket, name, data):
+ self.objects[(bucket, name)] = data
+
+ def rm(self, bucket, name):
+ self.removed.append((bucket, name))
+ del self.objects[(bucket, name)]
+
+
+def fake_settings(monkeypatch):
+ storage = _FakeStorage()
+ monkeypatch.setattr(image_utils, "settings", SimpleNamespace(STORAGE_IMPL=storage))
+ return storage
+
+
+def test_store_chunk_image_replace_overwrites_existing(fake_settings):
+ fake_settings.put("kb-1", "chunk-1", _png_bytes(2, 2, "red"))
+ replacement = _png_bytes(3, 4, "blue")
+
+ image_utils.store_chunk_image("kb-1", "chunk-1", replacement, mode="replace")
+
+ assert fake_settings.objects[("kb-1", "chunk-1")] == replacement
+
+
+def test_store_chunk_image_append_merges_existing(fake_settings):
+ fake_settings.put("kb-1", "chunk-1", _png_bytes(2, 2, "red"))
+ appended = _png_bytes(1, 1, "blue")
+
+ image_utils.store_chunk_image("kb-1", "chunk-1", appended, mode="append")
+
+ merged = Image.open(BytesIO(fake_settings.objects[("kb-1", "chunk-1")]))
+ assert merged.size == (2, 3)
+
+
+def test_store_chunk_image_append_creates_when_missing(fake_settings):
+ new_image = _png_bytes(2, 2, "green")
+
+ image_utils.store_chunk_image("kb-1", "chunk-1", new_image, mode="append")
+
+ assert fake_settings.objects[("kb-1", "chunk-1")] == new_image
+
+
+def test_remove_chunk_image_deletes_existing_object(fake_settings):
+ fake_settings.put("kb-1", "chunk-1", b"image")
+
+ image_utils.remove_chunk_image("kb-1", "chunk-1")
+
+ assert fake_settings.removed == [("kb-1", "chunk-1")]
+ assert ("kb-1", "chunk-1") not in fake_settings.objects
+
+
+def test_remove_chunk_image_noop_when_missing(fake_settings):
+ image_utils.remove_chunk_image("kb-1", "chunk-1")
+
+ assert fake_settings.removed == []