Skip to content

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

fix(chunk): support image updates on the chunk PATCH endpoint (#20107)

jay77721efd15d18517f
diff --git a/internal/handler/chunk.go b/internal/handler/chunk.go
index 483ff91565..d18fd9510e 100644
--- a/internal/handler/chunk.go
+++ b/internal/handler/chunk.go
@@ -505,6 +505,21 @@ func parseAvailableBody(rawBody map[string]interface{}) (int, error) {
return 0, fmt.Errorf("`available_int` or `available` is required")
}
+// optionalBodyString reads an optional string field. A present field of another
+// JSON type is rejected instead of being silently ignored, so a client cannot
+// believe it sent an image that the server dropped.
+func optionalBodyString(rawBody map[string]interface{}, field, typeMessage string) (*string, error) {
+ raw, ok := rawBody[field]
+ if !ok {
+ return nil, nil
+ }
+ value, ok := raw.(string)
+ if !ok {
+ return nil, errors.New(typeMessage)
+ }
+ return &value, nil
+}
+
// UpdateChunk updates a chunk
// @Summary Update Chunk
// @Description Update chunk fields
@@ -553,6 +568,8 @@ func (h *ChunkHandler) UpdateChunk(c *gin.Context) {
"questions": true,
"available": true,
"positions": true,
+ "image_base64": true,
+ "image_update_mode": true,
// Accepted but never persisted: the UI always sends tag_kwd, so
// dropping it here would 400 every chunk edit. Go's tagger writes
// tag_feas; tag_kwd belongs to a Python tag dataset
@@ -563,7 +580,7 @@ func (h *ChunkHandler) UpdateChunk(c *gin.Context) {
}
for field := range rawBody {
if field != "dataset_id" && field != "document_id" && field != "chunk_id" && !allowedFields[field] {
- common.ResponseWithHttpCodeData(c, http.StatusBadRequest, 400, nil, "Update field '"+field+"' is not supported. Updatable fields: content, important_keywords, questions, available, positions, tag_feas")
+ common.ResponseWithHttpCodeData(c, http.StatusBadRequest, 400, nil, "Update field '"+field+"' is not supported. Updatable fields: content, important_keywords, questions, available, positions, image_base64, image_update_mode, tag_feas")
return
}
}
@@ -596,6 +613,18 @@ func (h *ChunkHandler) UpdateChunk(c *gin.Context) {
req.Positions = positions
}
req.TagFeas = rawBody["tag_feas"]
+ imageBase64, err := optionalBodyString(rawBody, "image_base64", "`image_base64` must be a non-empty string")
+ if err != nil {
+ common.ResponseWithHttpCodeData(c, http.StatusBadRequest, common.CodeDataError, nil, err.Error())
+ return
+ }
+ imageUpdateMode, err := optionalBodyString(rawBody, "image_update_mode", "`image_update_mode` must be a string")
+ if err != nil {
+ common.ResponseWithHttpCodeData(c, http.StatusBadRequest, common.CodeDataError, nil, err.Error())
+ return
+ }
+ req.ImageBase64 = imageBase64
+ req.ImageUpdateMode = imageUpdateMode
// Set path parameters
req.DatasetID = datasetID
@@ -603,7 +632,7 @@ func (h *ChunkHandler) UpdateChunk(c *gin.Context) {
req.ChunkID = chunkID
ctx := c.Request.Context()
- err := h.chunkService.UpdateChunk(ctx, &req, user.ID)
+ err = h.chunkService.UpdateChunk(ctx, &req, user.ID)
if err != nil {
var coded interface {
Code() common.ErrorCode
diff --git a/internal/handler/chunk_test.go b/internal/handler/chunk_test.go
index 166b86a6d9..6367cb5654 100644
--- a/internal/handler/chunk_test.go
+++ b/internal/handler/chunk_test.go
@@ -312,6 +312,107 @@ func TestChunkHandlerUpdateChunkValidationErrorIsBadRequest(t *testing.T) {
}
}
+func TestChunkHandlerUpdateChunkForwardsImageFields(t *testing.T) {
+ mock := &mockChunkSvc{}
+ r, h := setupChunkHandlerWithUser("user-1", mock)
+ r.PATCH("/api/v1/datasets/:dataset_id/documents/:document_id/chunks/:chunk_id", h.UpdateChunk)
+
+ mock.updateChunkFn = func(ctx context.Context, req *service.UpdateChunkRequest, userID string) error {
+ if req.ImageBase64 == nil || *req.ImageBase64 != "aGVsbG8=" {
+ t.Fatalf("image_base64 = %v, want aGVsbG8=", req.ImageBase64)
+ }
+ if req.ImageUpdateMode == nil || *req.ImageUpdateMode != "replace" {
+ t.Fatalf("image_update_mode = %v, want replace", req.ImageUpdateMode)
+ }
+ return nil
+ }
+
+ req := httptest.NewRequest(http.MethodPatch, "/api/v1/datasets/kb-1/documents/doc-1/chunks/chunk-1",
+ strings.NewReader(`{"content":"updated","image_base64":"aGVsbG8=","image_update_mode":"replace"}`))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ r.ServeHTTP(w, req)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("status = %d, body = %s", w.Code, w.Body.String())
+ }
+}
+
+func TestChunkHandlerUpdateChunkRejectsNonStringImageFields(t *testing.T) {
+ cases := []struct {
+ name string
+ body string
+ want string
+ }{
+ {"image_base64 as number", `{"image_base64":123}`, "`image_base64` must be a non-empty string"},
+ {"image_base64 as null", `{"image_base64":null}`, "`image_base64` must be a non-empty string"},
+ {"image_update_mode as number", `{"image_update_mode":5}`, "`image_update_mode` must be a string"},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ mock := &mockChunkSvc{}
+ r, h := setupChunkHandlerWithUser("user-1", mock)
+ r.PATCH("/api/v1/datasets/:dataset_id/documents/:document_id/chunks/:chunk_id", h.UpdateChunk)
+
+ mock.updateChunkFn = func(context.Context, *service.UpdateChunkRequest, string) error {
+ t.Fatal("service must not be called for a malformed image field")
+ return nil
+ }
+
+ req := httptest.NewRequest(http.MethodPatch, "/api/v1/datasets/kb-1/documents/doc-1/chunks/chunk-1", strings.NewReader(tc.body))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ r.ServeHTTP(w, req)
+
+ if w.Code != http.StatusBadRequest {
+ t.Fatalf("status = %d, body = %s", w.Code, w.Body.String())
+ }
+ var resp map[string]interface{}
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatalf("decode response: %v", err)
+ }
+ message, _ := resp["message"].(string)
+ if message != tc.want {
+ t.Fatalf("message = %q, want %q", message, tc.want)
+ }
+ // Python answers the image paths with DATA_ERROR (102).
+ if resp["code"] != float64(common.CodeDataError) {
+ t.Fatalf("code = %v, want %d", resp["code"], common.CodeDataError)
+ }
+ })
+ }
+}
+
+func TestChunkHandlerUpdateChunkStillRejectsUnknownFields(t *testing.T) {
+ mock := &mockChunkSvc{}
+ r, h := setupChunkHandlerWithUser("user-1", mock)
+ r.PATCH("/api/v1/datasets/:dataset_id/documents/:document_id/chunks/:chunk_id", h.UpdateChunk)
+
+ mock.updateChunkFn = func(context.Context, *service.UpdateChunkRequest, string) error {
+ t.Fatal("service must not be called for an unsupported field")
+ return nil
+ }
+
+ req := httptest.NewRequest(http.MethodPatch, "/api/v1/datasets/kb-1/documents/doc-1/chunks/chunk-1", strings.NewReader(`{"doc_type_kwd":"image"}`))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ r.ServeHTTP(w, req)
+
+ if w.Code != http.StatusBadRequest {
+ t.Fatalf("status = %d, body = %s", w.Code, w.Body.String())
+ }
+ var resp map[string]interface{}
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatalf("decode response: %v", err)
+ }
+ message, _ := resp["message"].(string)
+ for _, field := range []string{"image_base64", "image_update_mode"} {
+ if !strings.Contains(message, field) {
+ t.Fatalf("message = %q, want it to list %s as updatable", message, field)
+ }
+ }
+}
+
func TestChunkRetrieval_EmptyQuestion(t *testing.T) {
r, _ := setupChunkRetrievalTest("user1")
diff --git a/internal/service/chunk/chunk.go b/internal/service/chunk/chunk.go
index e75a315e9a..eb82879f3a 100644
--- a/internal/service/chunk/chunk.go
+++ b/internal/service/chunk/chunk.go
@@ -51,12 +51,12 @@ import (
"ragflow/internal/utility"
)
-var chunkImageMergeLocks = struct {
+var chunkImageLocks = struct {
sync.Mutex
- locks map[string]*chunkImageMergeLock
-}{locks: make(map[string]*chunkImageMergeLock)}
+ locks map[string]*chunkImageLock
+}{locks: make(map[string]*chunkImageLock)}
-type chunkImageMergeLock struct {
+type chunkImageLock struct {
mu sync.Mutex
refs int
}
@@ -97,7 +97,9 @@ type ChunkService struct {
getEmbeddingModelFunc func(string, string) (*models.EmbeddingModel, error)
incrementChunkStatsFunc func(string, string, int64, int64, float64) error
decrementChunkStatsFunc func(string, string, int64, int64, float64) error
- storeChunkImageFunc func(string, string, []byte) error
+ storeChunkImageFunc func(string, string, []byte, string) error
+ removeChunkImageFunc func(string, string) error
+ markWikiDirtyFunc func(tenantID, datasetID, documentID string, chunkIDs []string)
tokenizeFunc func(string) (string, error)
fineGrainedTokenizeFunc func(string) (string, error)
numTokensFunc func(string) int
@@ -1210,6 +1212,39 @@ func (s *ChunkService) UpdateChunk(ctx context.Context, req *service.UpdateChunk
d["tag_feas"] = tagFeas
}
+ // Image (Python: chunk_api.update_chunk). The image is stored before the
+ // index update and dropped from storage only after it, so a failed update
+ // never leaves the index pointing at a deleted image.
+ removeImageAfterUpdate := false
+ if req.ImageUpdateMode != nil || req.ImageBase64 != nil {
+ imageMode, err := parseImageUpdateMode(req.ImageUpdateMode)
+ if err != nil {
+ return updateChunkError{code: common.CodeDataError, message: err.Error()}
+ }
+ switch {
+ case imageMode == imageUpdateModeRemove:
+ d["img_id"] = ""
+ d["doc_type_kwd"] = "text"
+ removeImageAfterUpdate = true
+ case req.ImageBase64 != nil:
+ imageBinary, err := decodeChunkImageBase64(*req.ImageBase64)
+ if err != nil {
+ return updateChunkError{code: common.CodeDataError, message: err.Error()}
+ }
+ if err = s.storeChunkImage(ctx, req.DatasetID, req.ChunkID, imageBinary, imageMode); err != nil {
+ common.Error("failed to store chunk image", err,
+ zap.String("dataset_id", req.DatasetID),
+ zap.String("chunk_id", req.ChunkID),
+ zap.String("mode", imageMode))
+ return updateChunkError{code: common.CodeDataError, message: "Failed to store chunk image"}
+ }
+ d["img_id"] = fmt.Sprintf("%s-%s", req.DatasetID, req.ChunkID)
+ d["doc_type_kwd"] = "image"
+ default:
+ return updateChunkError{code: common.CodeDataError, message: "`image_base64` is required when `image_update_mode` is `append` or `replace`"}
+ }
+ }
+
// Always include id
d["id"] = req.ChunkID
@@ -1223,9 +1258,21 @@ func (s *ChunkService) UpdateChunk(ctx context.Context, req *service.UpdateChunk
if err != nil {
return fmt.Errorf("failed to update chunk: %w", err)
}
+ // The index update above already committed, so a failing image removal must
+ // not skip the Wiki refresh for a content/availability change in the same
+ // request. The request still answers with the removal error (the Python
+ // reference does the same); the stored object is an orphan by then.
if req.Content != nil || req.Available != nil {
s.markWikiDirty(ctx, targetTenantID, req.DatasetID, req.DocumentID, []string{req.ChunkID})
}
+ if removeImageAfterUpdate {
+ if err = s.removeChunkImage(ctx, req.DatasetID, req.ChunkID); err != nil {
+ common.Error("failed to remove chunk image", err,
+ zap.String("dataset_id", req.DatasetID),
+ zap.String("chunk_id", req.ChunkID))
+ return updateChunkError{code: common.CodeDataError, message: "Failed to remove chunk image"}
+ }
+ }
return nil
}
@@ -1393,7 +1440,11 @@ func (s *ChunkService) AddChunk(ctx context.Context, req *service.AddChunkReques
if err != nil {
return nil, addChunkError{code: common.CodeDataError, message: err.Error()}
}
- if err = s.storeChunkImage(ctx, req.DatasetID, chunkID, imageBinary); err != nil {
+ if err = s.storeChunkImage(ctx, req.DatasetID, chunkID, imageBinary, imageUpdateModeAppend); err != nil {
+ common.Error("failed to store chunk image", err,
+ zap.String("dataset_id", req.DatasetID),
+ zap.String("chunk_id", chunkID),
+ zap.String("mode", imageUpdateModeAppend))
return nil, addChunkError{code: common.CodeDataError, message: "Failed to store chunk image"}
}
chunkData["img_id"] = fmt.Sprintf("%s-%s", req.DatasetID, chunkID)
@@ -1454,6 +1505,10 @@ func (s *ChunkService) AddChunk(ctx context.Context, req *service.AddChunkReques
}
func (s *ChunkService) markWikiDirty(ctx context.Context, tenantID, datasetID, documentID string, chunkIDs []string) {
+ if s.markWikiDirtyFunc != nil {
+ s.markWikiDirtyFunc(tenantID, datasetID, documentID, chunkIDs)
+ return
+ }
markCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 15*time.Second)
defer cancel()
if err := knowledge_compile.MarkWikiDocumentDirty(markCtx, tenantID, datasetID, documentID, chunkIDs); err != nil {
@@ -1556,6 +1611,26 @@ func decodeChunkImageBase64(raw string) ([]byte, error) {
return imageBinary, nil
}
+const (
+ imageUpdateModeAppend = "append"
+ imageUpdateModeReplace = "replace"
+ imageUpdateModeRemove = "remove"
+)
+
+// parseImageUpdateMode resolves the image update mode, defaulting to append
+// when the caller leaves it out (Python: chunk_api._parse_image_update_mode).
+func parseImageUpdateMode(raw *string) (string, error) {
+ if raw == nil {
+ return imageUpdateModeAppend, nil
+ }
+ switch mode := strings.ToLower(strings.TrimSpace(*raw)); mode {
+ case imageUpdateModeAppend, imageUpdateModeReplace, imageUpdateModeRemove:
+ return mode, nil
+ default:
+ return "", fmt.Errorf("`image_update_mode` must be one of: append, replace, remove")
+ }
+}
+
func mergeChunkEmbeddings(a, b []float64) ([]float64, error) {
if len(a) == 0 || len(b) == 0 || len(a) != len(b) {
return nil, fmt.Errorf("unexpected embedding dimensions")
@@ -1676,22 +1751,31 @@ func (s *ChunkService) decrementChunkStats(docID, kbID string, tokenNum, chunkNu
})
}
-func (s *ChunkService) storeChunkImage(ctx context.Context, bucket, chunkID string, imageBinary []byte) error {
+// storeChunkImage writes imageBinary under (bucket, chunkID). In append mode an
+// existing image is stacked below the new one; replace mode overwrites it
+// (Python: api/utils/image_utils.store_chunk_image). Every mode holds the same
+// per-chunk lock: a replace landing between an append's read and write would
+// otherwise be overwritten by the merged image.
+func (s *ChunkService) storeChunkImage(ctx context.Context, bucket, chunkID string, imageBinary []byte, mode string) error {
if s.storeChunkImageFunc != nil {
- return s.storeChunkImageFunc(bucket, chunkID, imageBinary)
+ return s.storeChunkImageFunc(bucket, chunkID, imageBinary, mode)
}
storageImpl := storage.GetStorageFactory().GetStorage()
if storageImpl == nil {
return fmt.Errorf("storage not initialized")
}
lockKey := bucket + "/" + chunkID
- lock := acquireChunkImageMergeLock(lockKey)
+ lock := acquireChunkImageLock(lockKey)
lock.mu.Lock()
defer func() {
lock.mu.Unlock()
- releaseChunkImageMergeLock(lockKey)
+ releaseChunkImageLock(lockKey)
}()
+ if mode == imageUpdateModeReplace {
+ return storageImpl.Put(ctx, bucket, chunkID, imageBinary)
+ }
+
if !storageImpl.ObjExist(ctx, bucket, chunkID) {
return storageImpl.Put(ctx, bucket, chunkID, imageBinary)
}
@@ -1726,29 +1810,55 @@ func (s *ChunkService) storeChunkImage(ctx context.Context, bucket, chunkID stri
return storageImpl.Put(ctx, bucket, chunkID, buf.Bytes())
}
-func acquireChunkImageMergeLock(key string) *chunkImageMergeLock {
- chunkImageMergeLocks.Lock()
- defer chunkImageMergeLocks.Unlock()
+// removeChunkImage drops a chunk's stored image, tolerating a missing object
+// (Python: api/utils/image_utils.remove_chunk_image). It takes the same
+// per-chunk lock as storeChunkImage, so a delete cannot slip into an append's
+// read-modify-write and leave the index pointing at a deleted object.
+func (s *ChunkService) removeChunkImage(ctx context.Context, bucket, chunkID string) error {
+ if s.removeChunkImageFunc != nil {
+ return s.removeChunkImageFunc(bucket, chunkID)
+ }
+ storageImpl := storage.GetStorageFactory().GetStorage()
+ if storageImpl == nil {
+ return fmt.Errorf("storage not initialized")
+ }
+ lockKey := bucket + "/" + chunkID
+ lock := acquireChunkImageLock(lockKey)
+ lock.mu.Lock()
+ defer func() {
+ lock.mu.Unlock()
+ releaseChunkImageLock(lockKey)
+ }()
+
+ if !storageImpl.ObjExist(ctx, bucket, chunkID) {
+ return nil
+ }
+ return storageImpl.Remove(ctx, bucket, chunkID)
+}
+
+func acquireChunkImageLock(key string) *chunkImageLock {
+ chunkImageLocks.Lock()
+ defer chunkImageLocks.Unlock()
- lock := chunkImageMergeLocks.locks[key]
+ lock := chunkImageLocks.locks[key]
if lock == nil {
- lock = &chunkImageMergeLock{}
- chunkImageMergeLocks.locks[key] = lock
+ lock = &chunkImageLock{}
+ chunkImageLocks.locks[key] = lock
}
lock.refs++
return lock
}
-func releaseChunkImageMergeLock(key string) {
- chunkImageMergeLocks.Lock()
- defer chunkImageMergeLocks.Unlock()
+func releaseChunkImageLock(key string) {
+ chunkImageLocks.Lock()
+ defer chunkImageLocks.Unlock()
- lock := chunkImageMergeLocks.locks[key]
+ lock := chunkImageLocks.locks[key]
if lock == nil {
return
}
lock.refs--
if lock.refs == 0 {
- delete(chunkImageMergeLocks.locks, key)
+ delete(chunkImageLocks.locks, key)
}
}
diff --git a/internal/service/chunk/chunk_test.go b/internal/service/chunk/chunk_test.go
index fdc2c20832..9119de75bc 100644
--- a/internal/service/chunk/chunk_test.go
+++ b/internal/service/chunk/chunk_test.go
@@ -3,9 +3,11 @@ package chunk
import (
"bytes"
"context"
+ "encoding/base64"
"errors"
"image"
"image/color"
+ _ "image/jpeg"
"image/png"
"ragflow/internal/common"
"ragflow/internal/dao"
@@ -751,6 +753,254 @@ func TestUpdateChunkUpdatesSameDocumentWithDocumentCondition(t *testing.T) {
}
}
+func TestUpdateChunkStoresImageAndFlagsImageChunk(t *testing.T) {
+ cases := []struct {
+ name string
+ mode *string
+ wantMode string
+ }{
+ {"mode defaults to append", nil, imageUpdateModeAppend},
+ {"mode is normalized", strPtr(" REPLACE "), imageUpdateModeReplace},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ db := setupChunkTestDB(t)
+ pushChunkTestDB(t, db)
+ insertChunkTestUserTenant(t, "user-1", "tenant-1")
+ insertChunkTestKB(t, "kb-1", "tenant-1")
+ insertChunkTestDoc(t, "doc-a", "kb-1")
+
+ engine := &updateChunkTestEngine{
+ existingChunk: map[string]interface{}{
+ "doc_id": "doc-a",
+ "content_with_weight": "existing content",
+ },
+ }
+ var storedBucket, storedChunkID, storedMode string
+ var storedBinary []byte
+ svc := &ChunkService{
+ docEngine: engine,
+ kbDAO: dao.NewKnowledgebaseDAO(),
+ userTenantDAO: dao.NewUserTenantDAO(),
+ storeChunkImageFunc: func(bucket, chunkID string, imageBinary []byte, mode string) error {
+ storedBucket, storedChunkID, storedMode, storedBinary = bucket, chunkID, mode, imageBinary
+ return nil
+ },
+ }
+
+ imageBase64 := base64.StdEncoding.EncodeToString([]byte("image-bytes"))
+ err := svc.UpdateChunk(t.Context(), &service.UpdateChunkRequest{
+ DatasetID: "kb-1",
+ DocumentID: "doc-a",
+ ChunkID: "chunk-1",
+ ImageBase64: &imageBase64,
+ ImageUpdateMode: tc.mode,
+ }, "user-1")
+ if err != nil {
+ t.Fatalf("UpdateChunk() error = %v", err)
+ }
+
+ if storedBucket != "kb-1" || storedChunkID != "chunk-1" || storedMode != tc.wantMode {
+ t.Fatalf("store args = %q/%q/%q, want kb-1/chunk-1/%s", storedBucket, storedChunkID, storedMode, tc.wantMode)
+ }
+ if string(storedBinary) != "image-bytes" {
+ t.Fatalf("stored binary = %q, want image-bytes", storedBinary)
+ }
+
+ if len(engine.updateCalls) != 1 {
+ t.Fatalf("UpdateChunks calls = %d, want 1", len(engine.updateCalls))
+ }
+ updated := engine.updateCalls[0].newValue
+ if updated["img_id"] != "kb-1-chunk-1" {
+ t.Fatalf("img_id = %#v, want kb-1-chunk-1", updated["img_id"])
+ }
+ if updated["doc_type_kwd"] != "image" {
+ t.Fatalf("doc_type_kwd = %#v, want image", updated["doc_type_kwd"])
+ }
+ })
+ }
+}
+
+func TestUpdateChunkRemoveModeClearsImageAfterIndexUpdate(t *testing.T) {
+ db := setupChunkTestDB(t)
+ pushChunkTestDB(t, db)
+ insertChunkTestUserTenant(t, "user-1", "tenant-1")
+ insertChunkTestKB(t, "kb-1", "tenant-1")
+ insertChunkTestDoc(t, "doc-a", "kb-1")
+
+ order := &[]string{}
+ engine := &orderedUpdateChunkTestEngine{
+ updateChunkTestEngine: updateChunkTestEngine{
+ existingChunk: map[string]interface{}{
+ "doc_id": "doc-a",
+ "content_with_weight": "existing content",
+ },
+ },
+ order: order,
+ }
+ svc := &ChunkService{
+ docEngine: engine,
+ kbDAO: dao.NewKnowledgebaseDAO(),
+ userTenantDAO: dao.NewUserTenantDAO(),
+ storeChunkImageFunc: func(string, string, []byte, string) error {
+ t.Fatal("remove mode must not store an image")
+ return nil
+ },
+ removeChunkImageFunc: func(bucket, chunkID string) error {
+ *order = append(*order, "storage")
+ if bucket != "kb-1" || chunkID != "chunk-1" {
+ t.Fatalf("remove args = %q/%q, want kb-1/chunk-1", bucket, chunkID)
+ }
+ return nil
+ },
+ }
+
+ removeMode := imageUpdateModeRemove
+ err := svc.UpdateChunk(t.Context(), &service.UpdateChunkRequest{
+ DatasetID: "kb-1",
+ DocumentID: "doc-a",
+ ChunkID: "chunk-1",
+ ImageUpdateMode: &removeMode,
+ }, "user-1")
+ if err != nil {
+ t.Fatalf("UpdateChunk() error = %v", err)
+ }
+
+ if len(engine.updateCalls) != 1 {
+ t.Fatalf("UpdateChunks calls = %d, want 1", len(engine.updateCalls))
+ }
+ updated := engine.updateCalls[0].newValue
+ if imgID, ok := updated["img_id"]; !ok || imgID != "" {
+ t.Fatalf("img_id = %#v, want empty string", updated["img_id"])
+ }
+ if updated["doc_type_kwd"] != "text" {
+ t.Fatalf("doc_type_kwd = %#v, want text", updated["doc_type_kwd"])
+ }
+ if !reflect.DeepEqual(*order, []string{"index", "storage"}) {
+ t.Fatalf("call order = %#v, want index before storage removal", *order)
+ }
+}
+
+// A request that changes content and drops the image must still schedule the
+// Wiki refresh when the stored object cannot be deleted: the index update has
+// already committed by then.
+func TestUpdateChunkMarksWikiDirtyWhenImageRemovalFails(t *testing.T) {
+ db := setupChunkTestDB(t)
+ pushChunkTestDB(t, db)
+ insertChunkTestUserTenant(t, "user-1", "tenant-1")
+ insertChunkTestKB(t, "kb-1", "tenant-1")
+ insertChunkTestDoc(t, "doc-a", "kb-1")
+
+ engine := &updateChunkTestEngine{
+ existingChunk: map[string]interface{}{
+ "doc_id": "doc-a",
+ "content_with_weight": "existing content",
+ },
+ }
+ wikiCalls := 0
+ svc := &ChunkService{
+ docEngine: engine,
+ kbDAO: dao.NewKnowledgebaseDAO(),
+ userTenantDAO: dao.NewUserTenantDAO(),
+ removeChunkImageFunc: func(string, string) error {
+ return errors.New("storage unavailable")
+ },
+ markWikiDirtyFunc: func(tenantID, datasetID, documentID string, chunkIDs []string) {
+ wikiCalls++
+ },
+ }
+
+ removeMode := imageUpdateModeRemove
+ content := "updated content"
+ err := svc.UpdateChunk(t.Context(), &service.UpdateChunkRequest{
+ DatasetID: "kb-1",
+ DocumentID: "doc-a",
+ ChunkID: "chunk-1",
+ Content: &content,
+ ImageUpdateMode: &removeMode,
+ }, "user-1")
+ if err == nil || !strings.Contains(err.Error(), "Failed to remove chunk image") {
+ t.Fatalf("UpdateChunk() error = %v, want the removal failure", err)
+ }
+ if len(engine.updateCalls) != 1 {
+ t.Fatalf("UpdateChunks calls = %d, want 1", len(engine.updateCalls))
+ }
+ if wikiCalls != 1 {
+ t.Fatalf("markWikiDirty calls = %d, want 1 (the index update already committed)", wikiCalls)
+ }
+}
+
+func TestUpdateChunkRejectsInvalidImageInput(t *testing.T) {
+ cases := []struct {
+ name string
+ imageB64 *string
+ mode *string
+ wantError string
+ }{
+ {"undecodable base64", strPtr("not base64!!"), nil, "invalid `image_base64`"},
+ {"empty base64", strPtr(""), nil, "`image_base64` must be a non-empty string"},
+ {"unknown mode", strPtr("aGVsbG8="), strPtr("grow"), "`image_update_mode` must be one of: append, replace, remove"},
+ {"empty mode", strPtr("aGVsbG8="), strPtr(""), "`image_update_mode` must be one of: append, replace, remove"},
+ {"append without base64", nil, strPtr(imageUpdateModeAppend), "`image_base64` is required when `image_update_mode` is `append` or `replace`"},
+ {"replace without base64", nil, strPtr(imageUpdateModeReplace), "`image_base64` is required when `image_update_mode` is `append` or `replace`"},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ db := setupChunkTestDB(t)
+ pushChunkTestDB(t, db)
+ insertChunkTestUserTenant(t, "user-1", "tenant-1")
+ insertChunkTestKB(t, "kb-1", "tenant-1")
+ insertChunkTestDoc(t, "doc-a", "kb-1")
+
+ engine := &updateChunkTestEngine{
+ existingChunk: map[string]interface{}{
+ "doc_id": "doc-a",
+ "content_with_weight": "existing content",
+ },
+ }
+ svc := &ChunkService{
+ docEngine: engine,
+ kbDAO: dao.NewKnowledgebaseDAO(),
+ userTenantDAO: dao.NewUserTenantDAO(),
+ storeChunkImageFunc: func(string, string, []byte, string) error {
+ t.Fatal("invalid input must not reach storage")
+ return nil
+ },
+ }
+
+ err := svc.UpdateChunk(t.Context(), &service.UpdateChunkRequest{
+ DatasetID: "kb-1",
+ DocumentID: "doc-a",
+ ChunkID: "chunk-1",
+ ImageBase64: tc.imageB64,
+ ImageUpdateMode: tc.mode,
+ }, "user-1")
+ if err == nil || !strings.Contains(err.Error(), tc.wantError) {
+ t.Fatalf("UpdateChunk() error = %v, want %q", err, tc.wantError)
+ }
+ var coded interface {
+ Code() common.ErrorCode
+ }
+ if !errors.As(err, &coded) || coded.Code() != common.CodeDataError {
+ t.Fatalf("error code = %v, want %d (Python: DATA_ERROR)", err, common.CodeDataError)
+ }
+ if len(engine.updateCalls) != 0 {
+ t.Fatalf("UpdateChunks calls = %d, want 0", len(engine.updateCalls))
+ }
+ })
+ }
+}
+
+type orderedUpdateChunkTestEngine struct {
+ updateChunkTestEngine
+ order *[]string
+}
+
+func (e *orderedUpdateChunkTestEngine) UpdateChunks(ctx context.Context, condition, newValue map[string]interface{}, indexName, datasetID string) error {
+ *e.order = append(*e.order, "index")
+ return e.updateChunkTestEngine.UpdateChunks(ctx, condition, newValue, indexName, datasetID)
+}
+
func TestAddChunkSuccess(t *testing.T) {
ctx := t.Context()
db := setupChunkTestDB(t)
@@ -923,11 +1173,14 @@ func TestAddChunkImageAndTagFeatureValidation(t *testing.T) {
return models.NewEmbeddingModel(driver, &modelName, &models.APIConfig{}, 0), nil
},
incrementChunkStatsFunc: func(string, string, int64, int64, float64) error { return nil },
- storeChunkImageFunc: func(bucket, chunkID string, imageBinary []byte) error {
+ storeChunkImageFunc: func(bucket, chunkID string, imageBinary []byte, mode string) error {
storeCalls++
if bucket != datasetID || chunkID == "" || len(imageBinary) == 0 {
t.Fatalf("unexpected store args bucket=%s chunkID=%s len=%d", bucket, chunkID, len(imageBinary))
}
+ if mode != imageUpdateModeAppend {
+ t.Fatalf("store mode = %q, want %q", mode, imageUpdateModeAppend)
+ }
return nil
},
}
@@ -1046,12 +1299,141 @@ func TestStoreChunkImageMergesExistingImage(t *testing.T) {
})
svc := &ChunkService{}
- if err := svc.storeChunkImage(ctx, "kb-1", "chunk-1", newImage); err != nil {
+ if err := svc.storeChunkImage(ctx, "kb-1", "chunk-1", newImage, imageUpdateModeAppend); err != nil {
+ t.Fatalf("storeChunkImage() error = %v", err)
+ }
+ if mockStorage.putCalls != 1 {
+ t.Fatalf("put calls = %d, want 1", mockStorage.putCalls)
+ }
+ merged, format, err := image.Decode(bytes.NewReader(mockStorage.lastPut))
+ if err != nil {
+ t.Fatalf("decode stored image: %v", err)
+ }
+ if format != "jpeg" {
+ t.Fatalf("stored format = %q, want jpeg", format)
+ }
+ // Append stacks the new image below the old one.
+ if got, want := merged.Bounds().Dy(), 3; got != want {
+ t.Fatalf("merged height = %d, want %d", got, want)
+ }
+}
+
+func TestStoreChunkImageReplaceOverwritesExistingImage(t *testing.T) {
+ oldImage := mustEncodePNG(t, image.Rect(0, 0, 2, 2))
+ newImage := mustEncodePNG(t, image.Rect(0, 0, 1, 1))
+ mockStorage := &chunkImageStorage{
+ exists: true,
+ oldBinary: oldImage,
+ }
+ ctx := t.Context()
+
+ factory := storage.GetStorageFactory()
+ originalStorage := factory.GetStorage()
+ factory.SetStorage(mockStorage)
+ t.Cleanup(func() {
+ factory.SetStorage(originalStorage)
+ })
+
+ svc := &ChunkService{}
+ if err := svc.storeChunkImage(ctx, "kb-1", "chunk-1", newImage, imageUpdateModeReplace); err != nil {
t.Fatalf("storeChunkImage() error = %v", err)
}
if mockStorage.putCalls != 1 {
t.Fatalf("put calls = %d, want 1", mockStorage.putCalls)
}
+ if !bytes.Equal(mockStorage.lastPut, newImage) {
+ t.Fatalf("replace stored %d bytes, want the new image verbatim (%d bytes)", len(mockStorage.lastPut), len(newImage))
+ }
+}
+
+func TestRemoveChunkImageSkipsMissingObject(t *testing.T) {
+ mockStorage := &chunkImageStorage{exists: false}
+ factory := storage.GetStorageFactory()
+ originalStorage := factory.GetStorage()
+ factory.SetStorage(mockStorage)
+ t.Cleanup(func() {
+ factory.SetStorage(originalStorage)
+ })
+
+ svc := &ChunkService{}
+ if err := svc.removeChunkImage(t.Context(), "kb-1", "chunk-1"); err != nil {
+ t.Fatalf("removeChunkImage() error = %v", err)
+ }
+ if mockStorage.removeCalls != 0 {
+ t.Fatalf("remove calls = %d, want 0 for a missing object", mockStorage.removeCalls)
+ }
+
+ mockStorage.exists = true
+ if err := svc.removeChunkImage(t.Context(), "kb-1", "chunk-1"); err != nil {
+ t.Fatalf("removeChunkImage() error = %v", err)
+ }
+ if mockStorage.removeCalls != 1 {
+ t.Fatalf("remove calls = %d, want 1", mockStorage.removeCalls)
+ }
+}
+
+// Every image mode has to serialize on the chunk's per-chunk lock: without it a
+// replace (or a remove) can land between an append's read and write and be
+// overwritten by the merged image.
+func TestChunkImageOperationsShareThePerChunkLock(t *testing.T) {
+ chunkID := "chunk-locked"
+ mockStorage := &chunkImageStorage{
+ exists: true,
+ oldBinary: mustEncodePNG(t, image.Rect(0, 0, 2, 2)),
+ }
+ factory := storage.GetStorageFactory()
+ originalStorage := factory.GetStorage()
+ factory.SetStorage(mockStorage)
+ t.Cleanup(func() {
+ factory.SetStorage(originalStorage)
+ })
+
+ lockKey := "kb-1/" + chunkID
+ lock := acquireChunkImageLock(lockKey)
+ lock.mu.Lock()
+ defer releaseChunkImageLock(lockKey)
+
+ type result struct {
+ op string
+ err error
+ }
+ svc := &ChunkService{}
+ ctx := t.Context()
+ appendedImage := mustEncodePNG(t, image.Rect(0, 0, 1, 1))
+ replacedImage := mustEncodePNG(t, image.Rect(0, 0, 3, 3))
+
+ done := make(chan result, 3)
+ run := func(op string, fn func() error) {
+ go func() { done <- result{op: op, err: fn()} }()
+ }
+ run("append", func() error {
+ return svc.storeChunkImage(ctx, "kb-1", chunkID, appendedImage, imageUpdateModeAppend)
+ })
+ run("replace", func() error {
+ return svc.storeChunkImage(ctx, "kb-1", chunkID, replacedImage, imageUpdateModeReplace)
+ })
+ run("remove", func() error {
+ return svc.removeChunkImage(ctx, "kb-1", chunkID)
+ })
+
+ select {
+ case got := <-done:
+ lock.mu.Unlock()
+ t.Fatalf("%s finished while the chunk's image lock was held", got.op)
+ case <-time.After(200 * time.Millisecond):
+ }
+
+ lock.mu.Unlock()
+ for i := 0; i < 3; i++ {
+ select {
+ case got := <-done:
+ if got.err != nil {
+ t.Fatalf("%s: %v", got.op, got.err)
+ }
+ case <-time.After(5 * time.Second):
+ t.Fatal("an image operation did not finish after the lock was released")
+ }
+ }
}
func TestRemoveChunksDecrementsStatsAfterDelete(t *testing.T) {
@@ -1568,21 +1950,25 @@ func (e *updateChunkTestEngine) UpdateChunks(_ context.Context, condition, newVa
}
type chunkImageStorage struct {
- exists bool
- oldBinary []byte
- putCalls int
+ exists bool
+ oldBinary []byte
+ putCalls int
+ removeCalls int
+ lastPut []byte
}
func (s *chunkImageStorage) Type() string { return "chunk_image_storage" }
func (s *chunkImageStorage) Health(_ context.Context) bool { return true }
func (s *chunkImageStorage) Put(ctx context.Context, bucket, fnm string, binary []byte, tenantID ...string) error {
s.putCalls++
+ s.lastPut = binary
return nil
}
func (s *chunkImageStorage) Get(ctx context.Context, bucket, fnm string, tenantID ...string) ([]byte, error) {
return s.oldBinary, nil
}
func (s *chunkImageStorage) Remove(ctx context.Context, bucket, fnm string, tenantID ...string) error {
+ s.removeCalls++
return nil
}
func (s *chunkImageStorage) ObjExist(ctx context.Context, bucket, fnm string, tenantID ...string) bool {
diff --git a/internal/service/chunk_types.go b/internal/service/chunk_types.go
index f9e64eaee2..5f8b025926 100644
--- a/internal/service/chunk_types.go
+++ b/internal/service/chunk_types.go
@@ -150,6 +150,10 @@ type UpdateChunkRequest struct {
Available *bool `json:"available,omitempty"`
Positions []interface{} `json:"positions,omitempty"`
TagFeas interface{} `json:"tag_feas,omitempty"`
+ // ImageBase64 and ImageUpdateMode replace or drop the chunk's stored image.
+ // ImageUpdateMode is one of append (default), replace, remove.
+ ImageBase64 *string `json:"image_base64,omitempty"`
+ ImageUpdateMode *string `json:"image_update_mode,omitempty"`
}
// RemoveChunksRequest request for removing chunks
diff --git a/web/src/components/image/__tests__/image-cache.test.tsx b/web/src/components/image/__tests__/image-cache.test.tsx
new file mode 100644
index 0000000000..0b820fd97e
--- /dev/null
+++ b/web/src/components/image/__tests__/image-cache.test.tsx
@@ -0,0 +1,118 @@
+/*
+ * 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.
+ */
+
+import { act, renderHook, waitFor } from '@testing-library/react';
+import {
+ buildDocumentImageUrl,
+ evictDocumentImage,
+ useDocumentImageUrl,
+} from '../index';
+
+// A chunk keeps its img_id when its image is updated in place, so the cached
+// bytes have to be reachable again by (id, documentId) and droppable.
+
+describe('document image cache', () => {
+ let fetchMock: jest.Mock;
+ let createObjectUrlMock: jest.Mock;
+ let revokeObjectUrlMock: jest.Mock;
+
+ beforeEach(() => {
+ fetchMock = jest.fn().mockResolvedValue({
+ ok: true,
+ blob: async () => new Blob(['image-bytes']),
+ });
+ createObjectUrlMock = jest
+ .fn()
+ .mockImplementation((blob: Blob) => `blob:cached-${blob.size}`);
+ revokeObjectUrlMock = jest.fn();
+
+ global.fetch = fetchMock as unknown as typeof fetch;
+ URL.createObjectURL =
+ createObjectUrlMock as unknown as typeof URL.createObjectURL;
+ URL.revokeObjectURL =
+ revokeObjectUrlMock as unknown as typeof URL.revokeObjectURL;
+ });
+
+ it('serves the cached bytes until the image is evicted', async () => {
+ const id = 'kb-1-chunk-evict';
+ const documentId = 'doc-1';
+
+ const first = renderHook(() => useDocumentImageUrl(id, documentId));
+ await waitFor(() => expect(first.result.current).toBeTruthy());
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+
+ const second = renderHook(() => useDocumentImageUrl(id, documentId));
+ await waitFor(() => expect(second.result.current).toBeTruthy());
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+
+ evictDocumentImage(id, documentId);
+ expect(revokeObjectUrlMock).toHaveBeenCalledTimes(1);
+
+ renderHook(() => useDocumentImageUrl(id, documentId));
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+ });
+
+ it('does not let an evicted entry delete a newer one', async () => {
+ jest.useFakeTimers();
+ try {
+ const id = 'kb-1-chunk-stale';
+ const documentId = 'doc-1';
+
+ const first = renderHook(() => useDocumentImageUrl(id, documentId));
+ await waitFor(() => expect(first.result.current).toBeTruthy());
+
+ // Evicted while still mounted, then released: the release arms a 30s
+ // cleanup timer on an entry the map no longer holds.
+ evictDocumentImage(id, documentId);
+ first.unmount();
+
+ // A later mount fetches again and installs a fresh entry.
+ const second = renderHook(() => useDocumentImageUrl(id, documentId));
+ await waitFor(() => expect(second.result.current).toBeTruthy());
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+
+ act(() => {
+ jest.advanceTimersByTime(31000);
+ });
+
+ // The stale timer must leave the new entry alone (and not leak its blob).
+ renderHook(() => useDocumentImageUrl(id, documentId));
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+ } finally {
+ jest.useRealTimers();
+ }
+ });
+
+ it('fetches again when the cache-busting key changes', async () => {
+ const id = 'kb-1-chunk-buster';
+ const documentId = 'doc-1';
+
+ const first = renderHook(() => useDocumentImageUrl(id, documentId, 1));
+ await waitFor(() => expect(first.result.current).toBeTruthy());
+ expect(fetchMock.mock.calls[0][0]).toContain('_t=1');
+
+ // Same image, new key: the replacement bytes must be fetched.
+ renderHook(() => useDocumentImageUrl(id, documentId, 2));
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+ expect(fetchMock.mock.calls[1][0]).toContain('_t=2');
+ });
+
+ it('omits the cache-busting key when none is given', () => {
+ expect(buildDocumentImageUrl('kb-1-chunk-plain', 'doc-1')).not.toContain(
+ '_t',
+ );
+ });
+});
diff --git a/web/src/components/image/index.tsx b/web/src/components/image/index.tsx
index e87ec9f41b..1c1dc95e50 100644
--- a/web/src/components/image/index.tsx
+++ b/web/src/components/image/index.tsx
@@ -30,6 +30,9 @@ interface IImage extends React.ImgHTMLAttributes<HTMLImageElement> {
type ImageCacheItem = {
count: number;
+ // The URL the bytes belong to, without the cache-busting `_t` query, so an
+ // entry can be found again no matter which `_t` fetched it.
+ baseUrl: string;
objectUrl?: string;
promise?: Promise<string>;
timer?: ReturnType<typeof setTimeout>;
@@ -55,12 +58,32 @@ export const buildDocumentImageUrl = (
return `${restAPIv1}${path}${query ? `?${query}` : ''}`;
};
+// Drop the cached bytes of one document image. A chunk keeps its img_id when
+// its image is updated in place, so mounted <Image>s would otherwise keep
+// rendering the previously fetched picture.
+export const evictDocumentImage = (id: string, documentId?: string) => {
+ const baseUrl = buildDocumentImageUrl(id, documentId);
+
+ imageCache.forEach((item, cacheKey) => {
+ if (item.baseUrl !== baseUrl) {
+ return;
+ }
+ if (item.timer) {
+ clearTimeout(item.timer);
+ }
+ if (item.objectUrl) {
+ URL.revokeObjectURL(item.objectUrl);
+ }
+ imageCache.delete(cacheKey);
+ });
+};
+
const fetchDocumentImage = (url: string, authorization: string) => {
const cacheKey = `${authorization}:${url}`;
let item = imageCache.get(cacheKey);
if (!item) {
- item = { count: 0 };
+ item = { count: 0, baseUrl: url.split('?')[0] };
imageCache.set(cacheKey, item);
}
if (item.timer) {
@@ -82,7 +105,10 @@ const fetchDocumentImage = (url: string, authorization: string) => {
return item.objectUrl;
})
.catch((error) => {
- imageCache.delete(cacheKey);
+ // A re-fetch may have installed a newer entry under this key.
+ if (imageCache.get(cacheKey) === item) {
+ imageCache.delete(cacheKey);
+ }
throw error;
});
}
@@ -97,7 +123,10 @@ const fetchDocumentImage = (url: string, authorization: string) => {
if (item.objectUrl) {
URL.revokeObjectURL(item.objectUrl);
}
- imageCache.delete(cacheKey);
+ // Eviction or a re-fetch may have replaced this entry meanwhile.
+ if (imageCache.get(cacheKey) === item) {
+ imageCache.delete(cacheKey);
+ }
}
}, 30000);
}
diff --git a/web/src/hooks/__tests__/use-chunk-request-image-eviction.test.tsx b/web/src/hooks/__tests__/use-chunk-request-image-eviction.test.tsx
new file mode 100644
index 0000000000..13ce65a7f9
--- /dev/null
+++ b/web/src/hooks/__tests__/use-chunk-request-image-eviction.test.tsx
@@ -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.
+ */
+
+import { useDocumentImageUrl } from '@/components/image';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { useCreateChunk } from '../use-chunk-request';
+
+const mockSetChunk = jest.fn();
+
+jest.mock('@/services/knowledge-service', () => ({
+ __esModule: true,
+ default: {
+ setChunk: (...args: unknown[]) => mockSetChunk(...args),
+ },
+}));
+
+// route-hook reads react-router's search params, which jsdom has no router for.
+jest.mock('@/hooks/route-hook', () => ({
+ useGetKnowledgeSearchParams: () => ({
+ type: '',
+ documentId: 'doc-1',
+ knowledgeId: 'kb-1',
+ }),
+}));
+
+// route-hook (imported by the hook chain) pulls in the app shell — routes
+// constructs a browser router at module scope, which jsdom cannot survive.
+jest.mock('@/routes', () => ({ Routes: {} }));
+
+function createWrapper() {
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ // `any` on purpose: files with jest.mock go through esbuild-jest's babel
+ // pass, which cannot strip imported bindings used as type annotations.
+ return function Wrapper({ children }: { children?: any }) {
+ return (
+ <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+ );
+ };
+}
+
+describe('useCreateChunk image eviction', () => {
+ let fetchMock: jest.Mock;
+
+ beforeEach(() => {
+ mockSetChunk.mockReset();
+ mockSetChunk.mockResolvedValue({ data: { code: 0 } });
+ fetchMock = jest.fn().mockResolvedValue({
+ ok: true,
+ blob: async () => new Blob(['image-bytes']),
+ });
+ global.fetch = fetchMock as unknown as typeof fetch;
+ URL.createObjectURL = jest.fn(
+ () => 'blob:cached',
+ ) as unknown as typeof URL.createObjectURL;
+ URL.revokeObjectURL = jest.fn() as unknown as typeof URL.revokeObjectURL;
+ });
+
+ it('drops the cached image of the chunk it updated', async () => {
+ const wrapper = createWrapper();
+ // The card renders the backend's img_id, `<dataset_id>-<chunk_id>`.
+ const image = renderHook(
+ () => useDocumentImageUrl('kb-1-chunk-1', 'doc-1'),
+ { wrapper },
+ );
+ await waitFor(() => expect(image.result.current).toBeTruthy());
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+
+ const { result } = renderHook(() => useCreateChunk(), { wrapper });
+ await act(async () => {
+ await result.current.createChunk({
+ chunk_id: 'chunk-1',
+ doc_id: 'doc-1',
+ kb_id: 'kb-1',
+ image_base64: 'aGVsbG8=',
+ });
+ });
+ expect(mockSetChunk).toHaveBeenCalledTimes(1);
+
+ renderHook(() => useDocumentImageUrl('kb-1-chunk-1', 'doc-1'), { wrapper });
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+ });
+});
diff --git a/web/src/hooks/use-chunk-request.ts b/web/src/hooks/use-chunk-request.ts
index d2b6b0df2e..fcfc1e10f4 100644
--- a/web/src/hooks/use-chunk-request.ts
+++ b/web/src/hooks/use-chunk-request.ts
@@ -14,6 +14,7 @@
* limitations under the License.
*/
+import { evictDocumentImage } from '@/components/image';
import message from '@/components/ui/message';
import { PaginationProps } from '@/interfaces/antd-compat';
import { ResponseGetType, ResponseType } from '@/interfaces/database/base';
@@ -101,6 +102,17 @@ export const useCreateChunk = () => {
});
if (data.code === 0) {
message.success(t('message.created'));
+ const updatedChunkId = payload.chunk_id || payload.id;
+ const updatedDatasetId = payload.kb_id || knowledgeId;
+ if (payload.image_base64 && updatedChunkId && updatedDatasetId) {
+ // The UI renders a chunk image under the backend's img_id,
+ // `<dataset_id>-<chunk_id>` (see the Go/Python chunk APIs). That id
+ // survives an image replacement, so it is the cache entry to drop.
+ evictDocumentImage(
+ `${updatedDatasetId}-${updatedChunkId}`,
+ payload.doc_id || payload.document_id,
+ );
+ }
setTimeout(() => {
queryClient.invalidateQueries({ queryKey: ['fetchChunkList'] });
}, 1000); // Delay to ensure the list is updated
@@ -176,7 +188,9 @@ export const useFetchNextChunkList = (
kb_id: knowledgeId,
doc_id: documentId,
page: chunkIds?.length ? 1 : pagination.current,
- size: chunkIds?.length ? chunkIds.length : Math.min(pagination.pageSize, 100),
+ size: chunkIds?.length
+ ? chunkIds.length
+ : Math.min(pagination.pageSize, 100),
available_int: available,
keywords: searchString,
chunk_ids: chunkIds,
diff --git a/web/src/pages/chunk/parsed-result/add-knowledge/components/knowledge-chunk/index.tsx b/web/src/pages/chunk/parsed-result/add-knowledge/components/knowledge-chunk/index.tsx
index 33960ca693..c78c3356df 100644
--- a/web/src/pages/chunk/parsed-result/add-knowledge/components/knowledge-chunk/index.tsx
+++ b/web/src/pages/chunk/parsed-result/add-knowledge/components/knowledge-chunk/index.tsx
@@ -68,6 +68,7 @@ function Chunk() {
handleInputChange,
available,
handleSetAvailable,
+ dataUpdatedAt,
} = useFetchNextChunkList(true, { chunkIds: filterChunkIds });
const { handleChunkCardClick, selectedChunkId } = useHandleChunkCardClick();
@@ -368,6 +369,10 @@ function Chunk() {
handleCheckboxClick={handleSingleCheckboxClick}
switchChunk={handleSwitchChunk}
clickChunkCard={handleChunkCardClick}
+ // Changes on every refetch, so a chunk whose image was
+ // replaced in place re-fetches it instead of reusing the
+ // cached bytes.
+ imageCacheKey={dataUpdatedAt}
/>
<footer className="mt-5">
@@ -410,6 +415,7 @@ interface ChunkVirtualListProps {
handleCheckboxClick: (chunkId: string, checked: boolean) => void;
switchChunk: (available?: number, chunkIds?: string[]) => void;
clickChunkCard: (chunkId: string) => void;
+ imageCacheKey?: string | number;
}
// Owned by a separate component so each result set can remount it (key from
@@ -425,6 +431,7 @@ function ChunkVirtualList({
handleCheckboxClick,
switchChunk,
clickChunkCard,
+ imageCacheKey,
}: ChunkVirtualListProps) {
const scrollContainerRef = useRef<HTMLDivElement>(null);
const virtualizer = useVirtualizer({
@@ -436,10 +443,7 @@ function ChunkVirtualList({
});
return (
- <div
- ref={scrollContainerRef}
- className="flex-1 overflow-y-auto min-h-0"
- >
+ <div ref={scrollContainerRef} className="flex-1 overflow-y-auto min-h-0">
<div
style={{
height: `${virtualizer.getTotalSize()}px`,
@@ -472,6 +476,7 @@ function ChunkVirtualList({
clickChunkCard={clickChunkCard}
selected={item.chunk_id === selectedChunkId}
textMode={textMode}
+ t={imageCacheKey}
/>
</div>
);