RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
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.pyindex 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_sizefrom 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.pyindex 7b93aa4923..e5ba51aff4 100644--- a/api/utils/image_utils.py+++ b/api/utils/image_utils.py@@ -20,21 +20,41 @@ from PIL import Imagefrom 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.pyindex 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"), insertedassert inserted.get("doc_type_kwd") == "image", insertedassert 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 == [], resdiff --git a/test/unit_test/api/utils/test_image_utils.py b/test/unit_test/api/utils/test_image_utils.pynew file mode 100644index 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 == []