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(parser): add media references for on-demand image materialization (#21561)
jay77721d697b0410ad6
diff --git a/internal/cli/user_command.go b/internal/cli/user_command.goindex 8380536be1..52efd7a2e2 100644--- a/internal/cli/user_command.go+++ b/internal/cli/user_command.go@@ -3027,6 +3027,9 @@ func (c *CLI) APIParseLocalFileCommand(commandCount int, cmd *Command) (Responseif err != nil {return nil, err}+ if fileType == utility.FileTypeHTML {+ fileParser = parser.NewHTMLTextParser()+ }fileContent, err := os.ReadFile(filename)if err != nil {diff --git a/internal/cli/user_command_test.go b/internal/cli/user_command_test.goindex 8cac6b984a..0ccaedfc15 100644--- a/internal/cli/user_command_test.go+++ b/internal/cli/user_command_test.go@@ -20,9 +20,26 @@ import ("encoding/json""fmt""net/http"+ "os"+ "path/filepath""testing")+func TestParseLocalHTMLWithInlineImage(t *testing.T) {+ filename := filepath.Join(t.TempDir(), "image.html")+ if err := os.WriteFile(filename, []byte(`<p>hello</p><img alt="image" src="data:image/png;base64,aGVsbG8=">`), 0600); err != nil {+ t.Fatal(err)+ }+ c := &CLI{Config: &CommandLineConfig{CLIMode: APIMode}}+ response, err := c.APIParseLocalFileCommand(1, &Command{Params: map[string]interface{}{"filename": filename}})+ if err != nil {+ t.Fatal(err)+ }+ if result, ok := response.(*SimpleResponse); !ok || result.Code != 0 {+ t.Fatalf("unexpected response: %#v", response)+ }+}+func TestDevUpdateChunkCommandUsesChunkResource(t *testing.T) {updated := make(chan struct{}, 1)client := newTestHTTPClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {diff --git a/internal/development.md b/internal/development.mdindex 808182e422..3b784556e9 100644--- a/internal/development.md+++ b/internal/development.md@@ -307,6 +307,10 @@ export KVROCKS_PORT=6379In docker the Go services override these to `kvrocks:6379` automatically(see `docker-compose-go.yml`). If Kvrocks is unreachable at startup theprocess fails fast with `failed to connect to Kvrocks`.+ HTML ingestion uses Kvrocks to hand inline images from the parser to the+ chunker; the ingestor also validates the injected Kvrocks client at startup.+ HTML image payloads default to a 32 MiB per-image limit; set+ `RAGFLOW_HTML_IMAGE_MAX_BYTES` to a positive byte count to change it.- Start RAGFlowdiff --git a/internal/engine/kvrocks/redis_test.go b/internal/engine/kvrocks/redis_test.goindex 1e638b1876..fa1026324d 100644--- a/internal/engine/kvrocks/redis_test.go+++ b/internal/engine/kvrocks/redis_test.go@@ -166,6 +166,18 @@ func TestClientSetNXDistinguishesContention(t *testing.T) {}}+func TestClientGetReturnsEmptyValueForMissingKey(t *testing.T) {+ r, _ := newStrictTestClient(t)++ got, err := r.Get(t.Context(), "missing")+ if err != nil {+ t.Fatalf("Get missing key returned error: %v", err)+ }+ if got != "" {+ t.Fatalf("Get missing key = %q, want empty string", got)+ }+}+func TestClientSetNXReturnsTransportError(t *testing.T) {r, mr := newStrictTestClient(t)mr.Close()diff --git a/internal/entity/media.go b/internal/entity/media.gonew file mode 100644index 0000000000..2076e6c984--- /dev/null+++ b/internal/entity/media.go@@ -0,0 +1,103 @@+// 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.++package entity++import (+ "crypto/sha256"+ "encoding/hex"+ "encoding/json"+ "strings"+)++// MediaKind names how a MediaRef locates its image bytes.+type MediaKind string++const (+ // MediaKindKV locates an image in the run-scoped Kvrocks media cache.+ MediaKindKV MediaKind = "kvrocks"+)++// MediaRef is a parser-emitted reference to deferred image bytes. A parser+// that emits one keeps image payloads out of its structured result. The+// ingestion run materializes the bytes through the reference's media cache.+type MediaRef struct {+ // Format is the parser family that produced the reference ("html", ...).+ Format string `json:"format"`+ // Kind is the locating scheme; see the MediaKind constants.+ Kind MediaKind `json:"kind"`+ // Scope binds the reference to one ingestion run. A cache lookup from a+ // different run is rejected instead of resolving a same-content image from+ // another task.+ Scope string `json:"scope,omitempty"`+ // SHA256 is the lowercase hex digest of the decoded image bytes. It is+ // both the lookup key and the integrity check after materialization.+ SHA256 string `json:"sha256"`+ // MIME is the image media type from the source ("image/png", ...).+ MIME string `json:"mime,omitempty"`+ // Size is the decoded image size in bytes.+ Size int64 `json:"size,omitempty"`+}++// Valid reports whether the reference carries the fields a resolver needs.+// The digest must be the lowercase hex form the parser emits: the resolver+// compares it as a string, so another spelling would turn a corrupt reference+// into a silent lookup miss.+func (r *MediaRef) Valid() bool {+ if r == nil || r.Format == "" || r.Kind == "" || len(r.SHA256) != sha256.Size*2 {+ return false+ }+ if strings.ToLower(r.SHA256) != r.SHA256 {+ return false+ }+ _, err := hex.DecodeString(r.SHA256)+ return err == nil+}++// IsZero reports whether the reference carries no field at all. JSON `{}`+// decodes into a non-nil zero value; consumers normalize it back to nil so an+// empty object keeps meaning "no reference".+func (r *MediaRef) IsZero() bool {+ return r == nil || (r.Format == "" && r.Kind == "" && r.Scope == "" && r.SHA256 == "" && r.MIME == "" && r.Size == 0)+}++// MediaRefFromAny decodes a media_ref value from either its typed form or a+// JSON-round-tripped map. It returns nil for absent or unusable values;+// callers that must reject a malformed reference check whether a value is+// present before calling it.+func MediaRefFromAny(v any) *MediaRef {+ switch ref := v.(type) {+ case nil:+ return nil+ case *MediaRef:+ if ref.Valid() {+ return ref+ }+ return nil+ case MediaRef:+ if ref.Valid() {+ return &ref+ }+ return nil+ }+ b, err := json.Marshal(v)+ if err != nil {+ return nil+ }+ var ref MediaRef+ if err := json.Unmarshal(b, &ref); err != nil || !ref.Valid() {+ return nil+ }+ return &ref+}diff --git a/internal/ingestion/component/chunker/common.go b/internal/ingestion/component/chunker/common.goindex 52904d86f7..5e0cbf7eef 100644--- a/internal/ingestion/component/chunker/common.go+++ b/internal/ingestion/component/chunker/common.go@@ -25,6 +25,7 @@ import ("ragflow/internal/agent/runtime""ragflow/internal/common"+ "ragflow/internal/entity""ragflow/internal/ingestion/component/schema""ragflow/internal/parser/chunk""ragflow/internal/parser/tableutil"@@ -223,6 +224,15 @@ func isMediaChunk(ck schema.ChunkDoc) bool {return typ == "image" || typ == "table"}+// hasMediaPayload reports whether a chunk still carries retrievable media:+// inline bytes, an uploaded reference, or a deferred media_ref that the+// upload pass will materialize. A present but unusable reference counts:+// dropping the item here would silently lose the image instead of letting+// the materializer reject it.+func hasMediaPayload(ck schema.ChunkDoc) bool {+ return ck.Image != "" || ck.ImgID != "" || ck.MediaRef != nil+}+// itemTextOrFallback returns the item's preferred text, or "".func itemTextOrFallback(it schema.ChunkDoc) string {if t, ok := itemText(it); ok {@@ -364,19 +374,22 @@ func chunkIDSource(ck schema.ChunkDoc) string {if text := canonicalChunkText(ck); text != "" {return text}- return mediaChunkIdentity(ck.Image, ck.ImgID)+ return mediaChunkIdentity(ck.Image, ck.ImgID, ck.MediaRef)}// mediaChunkIdentity returns the stable identity of a text-less media chunk:// a digest of the image payload when present (identical images collapse onto-// one id, which is harmless — they carry identical bytes), else the image-// reference. Empty when the chunk has neither, leaving the id the plain-// empty-text hash.-func mediaChunkIdentity(image, imgID string) string {+// one id, which is harmless — they carry identical bytes), else the+// content-addressed media reference, else the uploaded image id. Empty when+// the chunk has none of them, leaving the id the plain empty-text hash.+func mediaChunkIdentity(image, imgID string, ref *entity.MediaRef) string {if image != "" {sum := sha256.Sum256([]byte(image))return mediaChunkIDPrefix + hex.EncodeToString(sum[:])}+ if ref.Valid() {+ return mediaChunkIDPrefix + "sha256:" + ref.SHA256+ }if imgID != "" {return mediaChunkIDPrefix + imgID}diff --git a/internal/ingestion/component/chunker/general.go b/internal/ingestion/component/chunker/general.goindex f393f01328..a1ab96d8af 100644--- a/internal/ingestion/component/chunker/general.go+++ b/internal/ingestion/component/chunker/general.go@@ -1258,6 +1258,9 @@ func mergeGeneralMetadata(dst *schema.ChunkDoc, src schema.ChunkDoc) {if dst.ImgID == "" {dst.ImgID = src.ImgID}+ if dst.MediaRef == nil {+ dst.MediaRef = src.MediaRef+ }if dst.Layout == "" {dst.Layout = src.Layout}@@ -1454,7 +1457,7 @@ func finalizeGeneralChunks(chunks []schema.ChunkDoc, childrenPattern *regexp.Reg// media chunk (text may be only a position tag, or empty) must be// retained via its ImgID — otherwise the already-uploaded image is// dropped and its MinIO object orphaned.- if strings.TrimSpace(chunk.Text) == "" && chunk.Image == "" && chunk.ImgID == "" {+ if strings.TrimSpace(chunk.Text) == "" && !hasMediaPayload(chunk) {continue}visible = append(visible, chunk)diff --git a/internal/ingestion/component/chunker/group.go b/internal/ingestion/component/chunker/group.goindex aa3e5cdb37..3d7271a048 100644--- a/internal/ingestion/component/chunker/group.go+++ b/internal/ingestion/component/chunker/group.go@@ -340,6 +340,9 @@ func buildChunksFromRecordGroups(groups [][]lineRecord, prefixes []string, p *tiif first.image != "" {chunk["image"] = first.image}+ if first.mediaRef != nil {+ chunk["media_ref"] = first.mediaRef+ }if first.sheet != "" {chunk["sheet"] = first.sheet}@@ -627,7 +630,7 @@ func recordsFromStructured(items []schema.ChunkDoc) []lineRecord {// (materializeTableText); an image item legitimately carries no text —// its payload may be positions for on-demand cropping rather than inline// image bytes. Only a truly empty item is skipped.- if text == "" && it.Image == "" && it.ImgID == "" &&+ if text == "" && !hasMediaPayload(it) &&mergePositionMatrix(it.PDFPositions, it.Positions) == nil {continue}@@ -662,6 +665,7 @@ func recordsFromStructured(items []schema.ChunkDoc) []lineRecord {docType: dt,imgID: imgID,image: image,+ mediaRef: it.MediaRef,layout: it.Layout,pdfPositions: it.PDFPositions,positions: it.Positions,diff --git a/internal/ingestion/component/chunker/image_upload.go b/internal/ingestion/component/chunker/image_upload.goindex 60a5928460..f43f345e08 100644--- a/internal/ingestion/component/chunker/image_upload.go+++ b/internal/ingestion/component/chunker/image_upload.go@@ -14,12 +14,10 @@// limitations under the License.//-// Chunk image upload: at the moment a chunk's raw image is produced, upload it+// Chunk image upload: materialize deferred media from the run cache, upload it// to object storage, record the img_id reference, and drop the in-memory bytes.-// This bounds peak memory to a single chunk's image lifetime instead-// of carrying every image across the component boundary, matching the-// pdfcrop_cgo sliding-window philosophy. Mirrors Python image2id +-// upload_to_minio (rag/utils/base64_image.py, rag/svr/task_executor.py).+// This bounds peak memory to a single chunk's image lifetime instead of+// carrying every image across component boundaries.package chunkerimport (@@ -53,25 +51,66 @@ func imageUploadConcurrency() int {return 10}-// uploadChunkImages is the caller-side image-upload pass for a chunker's-// output. For each chunk it mirrors Python's upload_to_minio + image2id,-// running at the chunker stage (not in the Tokenizer) so the bytes are-// dropped as soon as they are produced:-// - img_id already set → keep it, skip upload (Python bypass).-// - no image → img_id="", nothing to upload.-// - otherwise → decode the image, upload the bytes via+// uploadChunkMedia is the caller-side image pass for a chunker's output. It+// runs at the chunker stage (not in the Tokenizer) so bytes are dropped as soon+// as they are uploaded:+// - img_id already set → keep it, skip upload (Python bypass).+// - no image or ref → img_id="", nothing to upload.+// - media_ref only → materialize one image from the run media cache.+// - otherwise → decode the image, upload the bytes via// uploadOneImage at key=ck["id"], set img_id="<kb_id>-<chunk_id>", and// delete the raw image field (用完即弃).//+// Materializing inside the loop keeps peak memory at one image instead of the+// whole document. Every cache, integrity, scope, or transport failure aborts+// the invocation; an image is never silently dropped.+//+// A chunk that already carries img_id skips resolution entirely: the image is+// already stored, so a reconstructed copy would only leak into the index.+//// The caller (imageUploadDecorator) must write ck["id"] before calling this-// function. uploadChunkImage errors when a chunk arrives without id.-func uploadChunkImages(ctx context.Context, chunks []map[string]any, up component.ImageUploader, kbID string) error {+// function.+func uploadChunkMedia(ctx context.Context, chunks []map[string]any, up component.ImageUploader, kbID, docID string) ([]map[string]any, error) {for _, ck := range chunks {+ imgID, _ := ck["img_id"].(string)+ if imgID != "" {+ // The image was already uploaded. A materialized copy would not+ // be uploaded again, so it must not survive into the index.+ delete(ck, "image")+ delete(ck, "media_ref")+ continue+ }++ image, _ := ck["image"].(string)+ if image == "" {+ data, ref, err := component.ResolveMediaRef(ctx, ck)+ if err != nil {+ if ctxErr := ctx.Err(); ctxErr != nil {+ return nil, ctxErr+ }+ return nil, fmt.Errorf("materialize media for document %s: %w", docID, err)+ }+ if ref != nil {+ chunkID, _ := ck["id"].(string)+ if chunkID == "" {+ return nil, fmt.Errorf("uploadChunkMedia: chunk missing id")+ }+ imgID, err := uploadOneImage(ctx, up, kbID, chunkID, data)+ if err != nil {+ return nil, err+ }+ ck["img_id"] = imgID+ delete(ck, "image")+ delete(ck, "media_ref")+ continue+ }+ }if err := uploadChunkImage(ctx, ck, up, kbID); err != nil {- return err+ return nil, err}+ delete(ck, "media_ref")}- return nil+ return chunks, nil}// uploadChunkImage handles a single chunk map: reads ck["id"] (required),diff --git a/internal/ingestion/component/chunker/image_upload_test.go b/internal/ingestion/component/chunker/image_upload_test.goindex ef60ba1154..78106fe294 100644--- a/internal/ingestion/component/chunker/image_upload_test.go+++ b/internal/ingestion/component/chunker/image_upload_test.go@@ -20,7 +20,9 @@ import ("bytes""context""encoding/base64"+ "errors""fmt"+ "strings""sync""sync/atomic""testing"@@ -28,8 +30,10 @@ import ("ragflow/internal/agent/runtime""ragflow/internal/common"+ "ragflow/internal/entity""ragflow/internal/ingestion/component/globals""ragflow/internal/ingestion/component/schema"+ medialib "ragflow/internal/parser/media"parserlib "ragflow/internal/parser/parser""gorm.io/gorm"@@ -53,8 +57,12 @@ func TestImageUploadDecorator_ParserUnpaddedImages(t *testing.T) {// The same PNG with its optional base64 padding omitted.uri := "data:image/png;base64," + pngBase64[:len(pngBase64)-2]var parsed parserlib.ParseResult+ ctx := t.Context()if format == "html" {- parsed = parserlib.NewHTMLParser().ParseWithResult(t.Context(), "image.html", []byte(`<img alt="caption" src="`+uri+`">`))+ source := []byte(`<img alt="caption" src="` + uri + `">`)+ cache := &chunkerMediaCache{}+ ctx = medialib.WithCache(ctx, cache)+ parsed = parserlib.NewHTMLParser().ParseWithResult(ctx, "image.html", source)} else {p, err := parserlib.NewMarkdownParser(parserlib.GoMarkdown)if err != nil {@@ -76,7 +84,7 @@ func TestImageUploadDecorator_ParserUnpaddedImages(t *testing.T) {if err != nil {t.Fatal(err)}- out, err := (&imageUploadDecorator{inner: comp}).Invoke(t.Context(), nil, map[string]any{+ out, err := (&imageUploadDecorator{inner: comp}).Invoke(ctx, nil, map[string]any{"name": "image." + format, "kb_id": testKBID, "doc_id": testDocID,"output_format": "json", "json": parsed.JSON,})@@ -129,7 +137,7 @@ func TestUploadOneImage_UploadsBytes(t *testing.T) {}// TestUploadChunkImages_WritesImgIDAndDropsImage pins the caller-side contract:-// uploadChunkImages reads ck["id"] (already written by the decorator prior to+// uploadChunkMedia reads ck["id"] (already written by the decorator prior to// calling upload), decodes the chunk's image, uploads via uploadOneImage, then// writes ck["img_id"] and deletes the raw image field.func TestUploadChunkImages_WritesImgIDAndDropsImage(t *testing.T) {@@ -141,8 +149,8 @@ func TestUploadChunkImages_WritesImgIDAndDropsImage(t *testing.T) {chunkID := common.ChunkID(testDocID, "caption")ck := map[string]any{"id": chunkID, "content_with_weight": "caption", "image": "data:image/png;base64," + pngBase64}- if err := uploadChunkImages(context.Background(), []map[string]any{ck}, up, testKBID); err != nil {- t.Fatalf("uploadChunkImages: %v", err)+ if _, err := uploadChunkMedia(context.Background(), []map[string]any{ck}, up, testKBID, testDocID); err != nil {+ t.Fatalf("uploadChunkMedia: %v", err)}wantImgID := testKBID + "-" + chunkIDif ck["img_id"] != wantImgID {@@ -170,8 +178,8 @@ func TestUploadChunkImages_SkipsWhenImgIDPresent(t *testing.T) {}chunkID := common.ChunkID(testDocID, "x")ck := map[string]any{"id": chunkID, "content_with_weight": "x", "img_id": "preset-img", "image": "data:image/png;base64," + pngBase64}- if err := uploadChunkImages(context.Background(), []map[string]any{ck}, up, testKBID); err != nil {- t.Fatalf("uploadChunkImages: %v", err)+ if _, err := uploadChunkMedia(context.Background(), []map[string]any{ck}, up, testKBID, testDocID); err != nil {+ t.Fatalf("uploadChunkMedia: %v", err)}if called {t.Error("uploader was called; expected skip when img_id preset")@@ -194,8 +202,8 @@ func TestUploadChunkImages_NoImage(t *testing.T) {}chunkID := common.ChunkID(testDocID, "text only")ck := map[string]any{"id": chunkID, "content_with_weight": "text only"}- if err := uploadChunkImages(context.Background(), []map[string]any{ck}, up, testKBID); err != nil {- t.Fatalf("uploadChunkImages: %v", err)+ if _, err := uploadChunkMedia(context.Background(), []map[string]any{ck}, up, testKBID, testDocID); err != nil {+ t.Fatalf("uploadChunkMedia: %v", err)}if called {t.Error("uploader was called for a chunk without image")@@ -215,7 +223,7 @@ func TestUploadChunkImage_ErrorOnMissingID(t *testing.T) {return "should-not-be-called", nil}ck := map[string]any{"content_with_weight": "x", "image": "data:image/png;base64," + pngBase64}- err := uploadChunkImages(context.Background(), []map[string]any{ck}, up, testKBID)+ _, err := uploadChunkMedia(context.Background(), []map[string]any{ck}, up, testKBID, testDocID)if err == nil {t.Fatal("expected error when chunk missing id")}@@ -469,3 +477,180 @@ func TestImageUploadDecorator_NoCapKeepsAll(t *testing.T) {t.Fatalf("len(chunks) = %d, want 5 (no cap should keep all)", len(chunks))}}++// TestImageUploadDecorator_ResolvesMediaRef pins the ref-mode path: the parser+// writes decoded bytes to the run cache, emits only a reference, and the upload+// pass materializes that reference without rescanning the source document.+func TestImageUploadDecorator_ResolvesMediaRef(t *testing.T) {+ want, err := base64.StdEncoding.DecodeString(pngBase64)+ if err != nil {+ t.Fatal(err)+ }+ uri := "data:image/png;base64," + pngBase64+ html := `<img src="` + uri + `">`++ p := parserlib.NewHTMLParser()+ cache := &chunkerMediaCache{}+ ctx := medialib.WithCache(t.Context(), cache)+ parsed := p.ParseWithResult(ctx, "image.html", []byte(html))+ if parsed.Err != nil {+ t.Fatal(parsed.Err)+ }+ ref := entity.MediaRefFromAny(parsed.JSON[0].ToMap()["media_ref"])+ if ref == nil {+ t.Fatal("parser emitted no media_ref")+ }++ var uploaded []byte+ prevUploader := ChunkImageUploader+ ChunkImageUploader = func(_ context.Context, kbID, chunkID string, data []byte) (string, error) {+ uploaded = append([]byte(nil), data...)+ return kbID + "-" + chunkID, nil+ }+ t.Cleanup(func() { ChunkImageUploader = prevUploader })++ comp, err := NewOneChunker(nil)+ if err != nil {+ t.Fatal(err)+ }+ out, err := (&imageUploadDecorator{inner: comp}).Invoke(ctx, nil, map[string]any{+ "name": "image.html", "kb_id": testKBID, "doc_id": testDocID,+ "output_format": "json", "json": parsed.JSON,+ })+ if err != nil {+ t.Fatalf("decorator: %v", err)+ }+ chunks, _ := schema.ChunkCarrierToMaps(out["chunks"])+ if len(chunks) != 1 {+ t.Fatalf("chunks = %d, want 1", len(chunks))+ }+ wantID := common.ChunkID(testDocID, mediaChunkIdentity("", "", ref))+ if chunks[0]["id"] != wantID {+ t.Errorf("id = %v, want %q", chunks[0]["id"], wantID)+ }+ if chunks[0]["img_id"] != testKBID+"-"+wantID {+ t.Errorf("img_id = %v, want %q", chunks[0]["img_id"], testKBID+"-"+wantID)+ }+ if !bytes.Equal(uploaded, want) {+ t.Errorf("uploaded %d bytes, want the source image", len(uploaded))+ }+ if _, ok := chunks[0]["media_ref"]; ok {+ t.Error("media_ref retained after upload")+ }+ if _, ok := chunks[0]["image"]; ok {+ t.Error("image bytes retained after upload")+ }+}++// TestImageUploadDecoratorFailsOnCacheMiss pins that a valid parser reference+// must remain materializable at upload time. A cache miss is a task failure,+// including for a captionless image that would otherwise look droppable.+func TestImageUploadDecoratorFailsOnCacheMiss(t *testing.T) {+ uri := "data:image/png;base64," + pngBase64++ p := parserlib.NewHTMLParser()+ cache := &chunkerMediaCache{}+ ctx := medialib.WithCache(t.Context(), cache)+ parsed := p.ParseWithResult(ctx, "image.html", []byte(`<img src="`+uri+`">`))+ if parsed.Err != nil {+ t.Fatal(parsed.Err)+ }+ cache.getErr = medialib.ErrMediaNotFound++ comp, err := NewOneChunker(nil)+ if err != nil {+ t.Fatal(err)+ }+ _, err = (&imageUploadDecorator{inner: comp}).Invoke(ctx, nil, map[string]any{+ "name": "image.html", "kb_id": testKBID, "doc_id": testDocID,+ "output_format": "json", "json": parsed.JSON,+ })+ if !errors.Is(err, medialib.ErrMediaNotFound) {+ t.Fatalf("decorator error = %v, want ErrMediaNotFound", err)+ }+}++// TestImageUploadDecoratorFailsOnCacheReadError pins that a backend failure is+// not converted into a missing-image skip.+func TestImageUploadDecoratorFailsOnCacheReadError(t *testing.T) {+ uri := "data:image/png;base64," + pngBase64++ p := parserlib.NewHTMLParser()+ cache := &chunkerMediaCache{}+ ctx := medialib.WithCache(t.Context(), cache)+ parsed := p.ParseWithResult(ctx, "image.html", []byte(`<img src="`+uri+`">`))+ if parsed.Err != nil {+ t.Fatal(parsed.Err)+ }+ backendErr := errors.New("kvrocks unavailable")+ cache.getErr = backendErr++ comp, err := NewOneChunker(nil)+ if err != nil {+ t.Fatal(err)+ }+ if _, err := (&imageUploadDecorator{inner: comp}).Invoke(ctx, nil, map[string]any{+ "name": "image.html", "kb_id": testKBID,+ "output_format": "json", "json": parsed.JSON,+ }); !errors.Is(err, backendErr) {+ t.Fatalf("decorator error = %v, want backend failure", err)+ }+}++// TestUploadChunkMediaSkipsMaterializationWhenImgIDExists pins the bypass:+// an already-uploaded image must not be reconstructed, and the redundant+// inline copy must not survive into the index.+func TestUploadChunkMediaSkipsMaterializationWhenImgIDExists(t *testing.T) {+ ref := entity.MediaRef{+ Format: "html",+ Kind: entity.MediaKindKV,+ Scope: "run-1",+ SHA256: strings.Repeat("a", 64),+ MIME: "image/png",+ Size: 5,+ }+ ck := map[string]any{+ "id": "chunk-1",+ "text": "",+ "doc_type_kwd": "image",+ "img_id": testKBID + "-chunk-1",+ "image": "data:image/png;base64," + pngBase64,+ "media_ref": ref,+ }+ up := func(context.Context, string, string, []byte) (string, error) {+ t.Fatal("upload must not run when img_id exists")+ return "", nil+ }+ kept, err := uploadChunkMedia(t.Context(), []map[string]any{ck}, up, testKBID, testDocID)+ if err != nil {+ t.Fatalf("uploadChunkMedia: %v", err)+ }+ if len(kept) != 1 {+ t.Fatalf("kept = %d, want 1", len(kept))+ }+ if _, ok := ck["image"]; ok {+ t.Error("redundant image survived the img_id bypass")+ }+ if _, ok := ck["media_ref"]; ok {+ t.Error("media_ref survived the img_id bypass")+ }+ if ck["img_id"] != testKBID+"-chunk-1" {+ t.Errorf("img_id = %v", ck["img_id"])+ }+}++// TestUploadChunkMediaRejectsInvalidMediaRef pins the malformed-reference+// path: a present ref that does not decode must fail the run, not persist a+// chunk without its image.+func TestUploadChunkMediaRejectsInvalidMediaRef(t *testing.T) {+ ck := map[string]any{+ "id": "chunk-1",+ "text": "",+ "doc_type_kwd": "image",+ "media_ref": map[string]any{"format": "html"},+ }+ up := func(context.Context, string, string, []byte) (string, error) { return "", nil }+ if _, err := uploadChunkMedia(t.Context(), []map[string]any{ck}, up, testKBID, testDocID); err == nil {+ t.Fatal("invalid media_ref was treated as absent")+ }+}diff --git a/internal/ingestion/component/chunker/media_ref_test.go b/internal/ingestion/component/chunker/media_ref_test.gonew file mode 100644index 0000000000..2b4478f673--- /dev/null+++ b/internal/ingestion/component/chunker/media_ref_test.go@@ -0,0 +1,433 @@+// 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.++package chunker++import (+ "context"+ "crypto/sha256"+ "encoding/hex"+ "errors"+ "strings"+ "testing"++ "ragflow/internal/agent/runtime"+ "ragflow/internal/entity"+ "ragflow/internal/ingestion/component/schema"+ medialib "ragflow/internal/parser/media"+ parserlib "ragflow/internal/parser/parser"+)++type chunkerMediaCache struct {+ data []byte+ getErr error+ gets int+}++func (c *chunkerMediaCache) Put(_ context.Context, format, mime string, data []byte) (entity.MediaRef, error) {+ c.data = append([]byte(nil), data...)+ sum := sha256.Sum256(data)+ return entity.MediaRef{+ Format: format,+ Kind: entity.MediaKindKV,+ Scope: "run-1",+ SHA256: hex.EncodeToString(sum[:]),+ MIME: mime,+ Size: int64(len(data)),+ }, nil+}++func (c *chunkerMediaCache) Get(context.Context, entity.MediaRef) ([]byte, error) {+ c.gets+++ if c.getErr != nil {+ return nil, c.getErr+ }+ return append([]byte(nil), c.data...), nil+}++func TestUploadChunkMedia_ReadsRepeatedReferenceFromCache(t *testing.T) {+ data := []byte("hello")+ cache := &chunkerMediaCache{data: data}+ ctx := medialib.WithCache(t.Context(), cache)+ ref, err := cache.Put(ctx, "html", "image/png", data)+ if err != nil {+ t.Fatal(err)+ }+ var uploaded [][]byte+ uploader := func(_ context.Context, kbID, chunkID string, payload []byte) (string, error) {+ uploaded = append(uploaded, append([]byte(nil), payload...))+ return kbID + "-" + chunkID, nil+ }+ chunks := []map[string]any{+ {"id": "chunk-1", "text": "first", "doc_type_kwd": "image", "media_ref": ref},+ {"id": "chunk-2", "text": "second", "doc_type_kwd": "image", "media_ref": ref},+ }+ kept, err := uploadChunkMedia(ctx, chunks, uploader, testKBID, testDocID)+ if err != nil {+ t.Fatalf("uploadChunkMedia: %v", err)+ }+ if len(kept) != 2 || cache.gets != 2 {+ t.Fatalf("kept/cache reads = %d/%d, want 2/2", len(kept), cache.gets)+ }+ for i, payload := range uploaded {+ if string(payload) != string(data) {+ t.Errorf("upload %d = %q, want %q", i, payload, data)+ }+ }+ for _, ck := range kept {+ if _, ok := ck["media_ref"]; ok {+ t.Errorf("media_ref survived upload: %#v", ck)+ }+ }+}++func TestUploadChunkMedia_CacheMissFailsEvenWithCaption(t *testing.T) {+ cache := &chunkerMediaCache{getErr: medialib.ErrMediaNotFound}+ ctx := medialib.WithCache(t.Context(), cache)+ ref := entity.MediaRef{+ Format: "html",+ Kind: entity.MediaKindKV,+ Scope: "run-1",+ SHA256: strings.Repeat("a", 64),+ MIME: "image/png",+ Size: 5,+ }+ chunks := []map[string]any{{+ "id": "chunk-1", "text": "caption", "doc_type_kwd": "image", "media_ref": ref,+ }}+ _, err := uploadChunkMedia(ctx, chunks, func(context.Context, string, string, []byte) (string, error) {+ t.Fatal("upload ran after a cache miss")+ return "", nil+ }, testKBID, testDocID)+ if !errors.Is(err, medialib.ErrMediaNotFound) {+ t.Fatalf("uploadChunkMedia error = %v, want ErrMediaNotFound", err)+ }+}++// mediaRefHTML is a caption-bearing image whose decoded bytes are written+// to the run media cache by the HTML parser.+const mediaRefHTML = `<img alt="figure" src="data:image/png;base64,` + pngBase64 + `">`++// runMediaRefChunker parses html, drives comp through the upload decorator,+// and returns the emitted chunk maps. The parser writes images into the same+// run cache the upload decorator later reads.+func runMediaRefChunker(t *testing.T, comp runtime.Component, docName, html string, params map[string]any) []map[string]any {+ t.Helper()++ cache := &chunkerMediaCache{}+ ctx := medialib.WithCache(t.Context(), cache)+ parsed := parserlib.NewHTMLParser().ParseWithResult(ctx, docName, []byte(html))+ if parsed.Err != nil {+ t.Fatal(parsed.Err)+ }++ prevUploader := ChunkImageUploader+ ChunkImageUploader = func(_ context.Context, kbID, chunkID string, _ []byte) (string, error) {+ return kbID + "-" + chunkID, nil+ }+ t.Cleanup(func() { ChunkImageUploader = prevUploader })++ in := map[string]any{+ "name": docName, "kb_id": testKBID,+ "output_format": "json", "json": parsed.JSON,+ }+ for k, v := range params {+ in[k] = v+ }+ out, err := (&imageUploadDecorator{inner: comp}).Invoke(ctx, nil, in)+ if err != nil {+ t.Fatalf("decorator: %v", err)+ }+ chunks, ok := schema.ChunkCarrierToMaps(out["chunks"])+ if !ok {+ t.Fatalf("chunks not []map[string]any: %T", out["chunks"])+ }+ return chunks+}++// uploadedMediaChunks returns the image chunks and pins the post-upload+// shape: every one carries the uploaded ID and no longer carries the+// reference or the bytes.+func uploadedMediaChunks(t *testing.T, chunks []map[string]any) []map[string]any {+ t.Helper()+ var images []map[string]any+ for _, ck := range chunks {+ if ck["doc_type_kwd"] != "image" {+ continue+ }+ images = append(images, ck)+ id, _ := ck["id"].(string)+ if id == "" {+ t.Fatalf("image chunk without id: %#v", ck)+ }+ if ck["img_id"] != testKBID+"-"+id {+ t.Errorf("img_id = %v, want the uploaded reference", ck["img_id"])+ }+ if _, ok := ck["media_ref"]; ok {+ t.Error("media_ref retained after upload")+ }+ if _, ok := ck["image"]; ok {+ t.Error("image bytes retained after upload")+ }+ }+ return images+}++// TestTokenChunkerResolvesMediaRef covers the default chunker variant: the+// reference survives unit construction and is materialized only at upload.+func TestTokenChunkerResolvesMediaRef(t *testing.T) {+ html := `<p>before</p><p>` + mediaRefHTML + `</p><p>after</p>`+ comp, err := NewTokenChunker(map[string]any{})+ if err != nil {+ t.Fatal(err)+ }+ // No doc_id: the TokenChunker would try to open a PDF engine from it, and+ // the test supplies the media source directly.+ chunks := runMediaRefChunker(t, comp, "deck.html", html, nil)+ if images := uploadedMediaChunks(t, chunks); len(images) != 1 {+ t.Fatalf("image chunks = %d, want 1", len(images))+ }+}++// TestTitleChunkerCarriesMediaRef covers the group/title path, which builds+// chunks from lineRecord values instead of ChunkDoc conversions.+func TestTitleChunkerCarriesMediaRef(t *testing.T) {+ html := `<h1>Heading</h1><p>body</p>` + mediaRefHTML+ comp, err := NewGroupTitleChunker(map[string]any{"levels": [][]string{{`^# `}}})+ if err != nil {+ t.Fatalf("NewGroupTitleChunker: %v", err)+ }+ chunks := runMediaRefChunker(t, comp, "title.html", html, nil)+ if images := uploadedMediaChunks(t, chunks); len(images) != 1 {+ t.Fatalf("image chunks = %d, want 1", len(images))+ }+}++// TestGeneralChunkerCarriesMediaRef covers the General chunker's finalize+// path, which keeps a media item alive by its reference.+func TestGeneralChunkerCarriesMediaRef(t *testing.T) {+ html := `<p>before</p>` + mediaRefHTML + `<p>after</p>`+ comp, err := NewGeneralChunker(map[string]any{"chunk_token_size": 128})+ if err != nil {+ t.Fatalf("NewGeneralChunker: %v", err)+ }+ chunks := runMediaRefChunker(t, comp, "general.html", html, map[string]any{"file_type": "html"})+ if images := uploadedMediaChunks(t, chunks); len(images) != 1 {+ t.Fatalf("image chunks = %d, want 1", len(images))+ }+}++// TestTokenChunkerKeepsTextlessMediaRef pins that a standalone image with no+// alt text is not dropped as an empty text chunk before materialization.+func TestTokenChunkerKeepsTextlessMediaRef(t *testing.T) {+ html := `<img src="data:image/png;base64,` + pngBase64 + `">`+ comp, err := NewTokenChunker(map[string]any{})+ if err != nil {+ t.Fatal(err)+ }+ chunks := runMediaRefChunker(t, comp, "no-alt.html", html, nil)+ if images := uploadedMediaChunks(t, chunks); len(images) != 1 {+ t.Fatalf("image chunks = %d, want 1", len(images))+ }+}++// TestImageUploadDecoratorRejectsUnusableMediaRef pins the error contract at+// the component boundary: a present reference that cannot be materialized+// must fail the run, even when the item has no text and would otherwise be+// filtered as empty.+func TestImageUploadDecoratorRejectsUnusableMediaRef(t *testing.T) {+ for _, tc := range []struct {+ name string+ items []map[string]any+ }{+ {+ name: "textless partial reference",+ items: []map[string]any{{"doc_type_kwd": "image", "media_ref": map[string]any{"format": "html"}}},+ },+ {+ name: "partial reference with text",+ items: []map[string]any{{"text": "caption", "media_ref": map[string]any{"format": "html"}}},+ },+ {+ name: "unknown reference fields",+ items: []map[string]any{{"text": "caption", "media_ref": map[string]any{"unknown": "value"}}},+ },+ {+ name: "malformed reference in a merged item list",+ items: []map[string]any{+ {"text": "kept"},+ {"doc_type_kwd": "image", "media_ref": map[string]any{"format": "html"}},+ },+ },+ {+ name: "short digest",+ items: []map[string]any{{+ "text": "caption",+ "media_ref": map[string]any{+ "format": "html",+ "kind": "kvrocks",+ "scope": "run-1",+ "sha256": strings.Repeat("a", 63),+ },+ }},+ },+ {+ name: "non-hex digest",+ items: []map[string]any{{+ "text": "caption",+ "media_ref": map[string]any{+ "format": "html",+ "kind": "kvrocks",+ "scope": "run-1",+ "sha256": strings.Repeat("z", 64),+ },+ }},+ },+ {+ name: "uppercase digest",+ items: []map[string]any{{+ "text": "caption",+ "media_ref": map[string]any{+ "format": "html",+ "kind": "kvrocks",+ "scope": "run-1",+ "sha256": strings.ToUpper(strings.Repeat("a", 64)),+ },+ }},+ },+ } {+ for _, chunker := range []struct {+ name string+ new func() (runtime.Component, error)+ }{+ {"one", func() (runtime.Component, error) { return NewOneChunker(nil) }},+ {"token", func() (runtime.Component, error) { return NewTokenChunker(map[string]any{}) }},+ } {+ t.Run(tc.name+"/"+chunker.name, func(t *testing.T) {+ comp, err := chunker.new()+ if err != nil {+ t.Fatal(err)+ }+ if _, err := (&imageUploadDecorator{inner: comp}).Invoke(t.Context(), nil, map[string]any{+ "name": "bad.html", "kb_id": testKBID,+ "output_format": "json", "json": tc.items,+ }); err == nil {+ t.Fatal("unusable media_ref was accepted")+ }+ })+ }+ }+}++// TestImageUploadDecoratorAcceptsEmptyMediaRef pins the other side: an empty+// object keeps meaning "no reference", so a text item survives and a textless+// item is still filtered as empty.+func TestImageUploadDecoratorAcceptsEmptyMediaRef(t *testing.T) {+ comp, err := NewOneChunker(nil)+ if err != nil {+ t.Fatal(err)+ }+ out, err := (&imageUploadDecorator{inner: comp}).Invoke(t.Context(), nil, map[string]any{+ "name": "empty-ref.html", "kb_id": testKBID, "doc_id": testDocID,+ "output_format": "json",+ "json": []any{+ map[string]any{"text": "kept", "media_ref": map[string]any{}},+ map[string]any{"doc_type_kwd": "image", "media_ref": map[string]any{}},+ },+ })+ if err != nil {+ t.Fatalf("empty media_ref failed: %v", err)+ }+ chunks, _ := schema.ChunkCarrierToMaps(out["chunks"])+ if len(chunks) != 1 {+ t.Fatalf("chunks = %d, want the text item only", len(chunks))+ }+ if chunks[0]["text"] != "kept" {+ t.Fatalf("text = %v, want kept", chunks[0]["text"])+ }+ if _, ok := chunks[0]["media_ref"]; ok {+ t.Fatal("empty media_ref reappeared on the wire")+ }+}++// TestQAChunkerCarriesMediaRef covers an image item whose alt text is a QA+// pair: the QA extractor must keep the reference so the upload pass can still+// materialize the attachment.+func TestQAChunkerCarriesMediaRef(t *testing.T) {+ html := `<img alt="question	answer" src="data:image/png;base64,` + pngBase64 + `">`+ comp, err := NewQAChunker(nil)+ if err != nil {+ t.Fatal(err)+ }+ chunks := runMediaRefChunker(t, comp, "qa.html", html, nil)+ if len(chunks) != 1 {+ t.Fatalf("chunks = %d, want 1", len(chunks))+ }+ if images := uploadedMediaChunks(t, chunks); len(images) != 1 {+ t.Fatalf("image chunks = %d, want 1", len(images))+ }+}++// TestOneChunkerRejectsInvalidMediaRefRegardlessOfOrder pins the merge+// invariant: only the first media attachment is kept, so every present+// reference must be validated before the merge. Otherwise a valid first+// reference hides a malformed later one and the run succeeds.+func TestOneChunkerRejectsInvalidMediaRefRegardlessOfOrder(t *testing.T) {+ html := `<img alt="figure" src="data:image/png;base64,` + pngBase64 + `">`+ cache := &chunkerMediaCache{}+ ctx := medialib.WithCache(t.Context(), cache)+ parsed := parserlib.NewHTMLParser().ParseWithResult(ctx, "order.html", []byte(html))+ if parsed.Err != nil {+ t.Fatal(parsed.Err)+ }+ var validRef *entity.MediaRef+ for _, item := range parsed.JSON {+ if m := item.ToMap(); m["doc_type_kwd"] == "image" {+ validRef = entity.MediaRefFromAny(m["media_ref"])+ }+ }+ if validRef == nil {+ t.Fatal("fixture emitted no valid media_ref")+ }++ valid := map[string]any{"text": "figure", "media_ref": validRef}+ invalid := map[string]any{"doc_type_kwd": "image", "media_ref": map[string]any{"format": "html"}}++ prevUploader := ChunkImageUploader+ ChunkImageUploader = func(_ context.Context, kbID, chunkID string, _ []byte) (string, error) {+ return kbID + "-" + chunkID, nil+ }+ t.Cleanup(func() { ChunkImageUploader = prevUploader })++ for _, tc := range []struct {+ name string+ items []map[string]any+ }{+ {"invalid first", []map[string]any{invalid, valid}},+ {"invalid last", []map[string]any{valid, invalid}},+ } {+ t.Run(tc.name, func(t *testing.T) {+ comp, err := NewOneChunker(nil)+ if err != nil {+ t.Fatal(err)+ }+ if _, err := (&imageUploadDecorator{inner: comp}).Invoke(ctx, nil, map[string]any{+ "name": "order.html", "kb_id": testKBID,+ "output_format": "json", "json": tc.items,+ }); err == nil {+ t.Fatal("invalid media_ref was accepted")+ }+ })+ }+}diff --git a/internal/ingestion/component/chunker/one.go b/internal/ingestion/component/chunker/one.goindex 52a685ae49..1eeb11eed7 100644--- a/internal/ingestion/component/chunker/one.go+++ b/internal/ingestion/component/chunker/one.go@@ -32,6 +32,7 @@ import ("strings""ragflow/internal/agent/runtime"+ "ragflow/internal/entity""ragflow/internal/ingestion/component/schema""gorm.io/gorm"@@ -137,7 +138,7 @@ func emitOneFromItems(items, chunks []schema.ChunkDoc) map[string]any {it := src[0]docType := itemDocType(it)text := itemTextOrFallback(it)- if strings.TrimSpace(text) == "" && it.Image == "" {+ if strings.TrimSpace(text) == "" && !hasMediaPayload(it) {return emptyOutputs()}out := schema.ChunkDoc{@@ -145,6 +146,8 @@ func emitOneFromItems(items, chunks []schema.ChunkDoc) map[string]any {Text: removeTag(text),DocType: docType,Image: it.Image,+ ImgID: it.ImgID,+ MediaRef: it.MediaRef,Positions: it.Positions,PDFPositions: it.PDFPositions,Sheet: it.Sheet,@@ -155,6 +158,7 @@ func emitOneFromItems(items, chunks []schema.ChunkDoc) map[string]any {var parts []stringvar img string+ var mediaRef *entity.MediaReffor _, it := range src {if t := itemTextOrFallback(it); t != "" {// Strip parser coordinate tags before joining (see emitOne).@@ -163,9 +167,12 @@ func emitOneFromItems(items, chunks []schema.ChunkDoc) map[string]any {if img == "" && it.Image != "" {img = it.Image}+ if mediaRef == nil && it.MediaRef != nil {+ mediaRef = it.MediaRef+ }}merged := strings.Join(parts, "\n")- if strings.TrimSpace(merged) == "" && img == "" {+ if strings.TrimSpace(merged) == "" && img == "" && mediaRef == nil {return emptyOutputs()}out := schema.ChunkDoc{Text: merged, DocType: "text"}@@ -177,6 +184,7 @@ func emitOneFromItems(items, chunks []schema.ChunkDoc) map[string]any {if img != "" {out.Image = img}+ out.MediaRef = mediaRefreturn chunkOutputs([]schema.ChunkDoc{out})}diff --git a/internal/ingestion/component/chunker/one_test.go b/internal/ingestion/component/chunker/one_test.goindex 6aa0d9c746..6612e00dbc 100644--- a/internal/ingestion/component/chunker/one_test.go+++ b/internal/ingestion/component/chunker/one_test.go@@ -156,3 +156,16 @@ func assertCoordTuple(t *testing.T, key string, got any, want []float64) {}}}++// TestOneChunkerKeepsImgIDForTextlessItem covers the single-item guard: an+// item kept alive by ImgID must carry that ID into the output chunk.+func TestOneChunkerKeepsImgIDForTextlessItem(t *testing.T) {+ out := emitOneFromItems([]schema.ChunkDoc{{DocType: "image", ImgID: "kb-1-chunk-1"}}, nil)+ chunks, _ := schema.ChunkCarrierToMaps(out["chunks"])+ if len(chunks) != 1 {+ t.Fatalf("chunks = %d, want 1", len(chunks))+ }+ if chunks[0]["img_id"] != "kb-1-chunk-1" {+ t.Fatalf("img_id = %v, want kb-1-chunk-1", chunks[0]["img_id"])+ }+}diff --git a/internal/ingestion/component/chunker/qa.go b/internal/ingestion/component/chunker/qa.goindex 88fac3b3cc..520607e58d 100644--- a/internal/ingestion/component/chunker/qa.go+++ b/internal/ingestion/component/chunker/qa.go@@ -38,7 +38,9 @@ import ("github.com/gomarkdown/markdown""github.com/gomarkdown/markdown/parser"+"gorm.io/gorm"+ "ragflow/internal/entity""ragflow/internal/agent/runtime""ragflow/internal/ingestion/component/schema"@@ -152,8 +154,9 @@ func (c *QAChunkerComponent) invoke(_ context.Context, inputs map[string]any) (mif pair.RowNum >= 0 {chunk.TopInt = []int{pair.RowNum}}- if pair.Image != "" {+ if pair.Image != "" || pair.MediaRef != nil {chunk.Image = pair.Image+ chunk.MediaRef = pair.MediaRefchunk.DocType = "image"}if len(pair.PDFPositions) > 0 {@@ -184,6 +187,7 @@ type qaPair struct {// chunk preserves metadata that Python sets via beAdocPdf/beAdocDocx//Image string+ MediaRef *entity.MediaRefPDFPositions json.RawMessagePositions json.RawMessageSheet string@@ -443,6 +447,7 @@ func extractQAJSON(items []schema.ChunkDoc, fileType string) []qaPair {p.Sheet = item.Sheetp.SheetIndex = item.SheetIndexp.Image = item.Image+ p.MediaRef = item.MediaRefp.PDFPositions = item.PDFPositionsif len(p.Positions) == 0 {p.Positions = item.Positionsdiff --git a/internal/ingestion/component/chunker/register.go b/internal/ingestion/component/chunker/register.goindex 0f5489d065..59c9e7a230 100644--- a/internal/ingestion/component/chunker/register.go+++ b/internal/ingestion/component/chunker/register.go@@ -27,9 +27,12 @@ package chunkerimport ("context"+ "errors"+ "strings""ragflow/internal/agent/runtime""ragflow/internal/common"+ "ragflow/internal/entity""ragflow/internal/ingestion/component/globals""ragflow/internal/ingestion/component/schema"@@ -59,7 +62,7 @@ func MustRegisterChunker(name string) {// imageUploadDecorator wraps a chunker component. Before upload it writes// ck["id"] (the single source of chunk identity) for every chunk; then it runs-// uploadChunkImages which reads ck["id"] and uploads any raw image bytes.+// uploadChunkMedia which reads ck["id"] and uploads raw or deferred images.type imageUploadDecorator struct {inner runtime.Component}@@ -69,6 +72,14 @@ func (d *imageUploadDecorator) Invoke(ctx context.Context, db *gorm.DB, inputs mif err != nil {return nil, err}+ // Chunkers report input-shape failures through _ERROR instead of a Go+ // error (the legacy flow contract). This decorator is the pipeline-facing+ // component, so promote that envelope to a real error: otherwise the run+ // continues with an empty chunk list and a malformed input looks like an+ // empty document.+ if msg, _ := out["_ERROR"].(string); strings.TrimSpace(msg) != "" {+ return nil, errors.New(msg)+ }// Accept the legacy []map[string]any carrier verbatim (no round-trip, so// the id-stamp/upload logic below sees the exact maps the chunker emitted).// The typed []ChunkDoc carrier is normalized via GetChunks, which also@@ -131,7 +142,7 @@ func (d *imageUploadDecorator) Invoke(ctx context.Context, db *gorm.DB, inputs mif text == "" {image, _ := ck["image"].(string)imgID, _ := ck["img_id"].(string)- text = mediaChunkIdentity(image, imgID)+ text = mediaChunkIdentity(image, imgID, entity.MediaRefFromAny(ck["media_ref"]))}ck["id"] = common.ChunkID(docID, text)}@@ -142,12 +153,13 @@ func (d *imageUploadDecorator) Invoke(ctx context.Context, db *gorm.DB, inputs m// persist run); in debug we drop the raw bytes so they are not held in// memory until a persist stage that will never run.if kbID != "" {- if err := uploadChunkImages(ctx, chunks, ChunkImageUploader, kbID); err != nil {+ if _, err := uploadChunkMedia(ctx, chunks, ChunkImageUploader, kbID, docID); err != nil {return nil, err}} else {for _, ck := range chunks {delete(ck, "image")+ delete(ck, "media_ref")}}return out, nildiff --git a/internal/ingestion/component/chunker/title.go b/internal/ingestion/component/chunker/title.goindex 282df0f280..241e8e0f4e 100644--- a/internal/ingestion/component/chunker/title.go+++ b/internal/ingestion/component/chunker/title.go@@ -67,6 +67,7 @@ import ("unicode/utf8""ragflow/internal/agent/runtime"+ "ragflow/internal/entity""ragflow/internal/ingestion/component/globals""ragflow/internal/ingestion/component/schema"@@ -641,6 +642,7 @@ type lineRecord struct {docType stringimgID *stringimage string+ mediaRef *entity.MediaReflayout stringpdfPositions json.RawMessagepositions json.RawMessagediff --git a/internal/ingestion/component/chunker/title_structured_media_test.go b/internal/ingestion/component/chunker/title_structured_media_test.goindex 9c0bdf3357..323697b57f 100644--- a/internal/ingestion/component/chunker/title_structured_media_test.go+++ b/internal/ingestion/component/chunker/title_structured_media_test.go@@ -308,7 +308,7 @@ func TestTitleFamilyEmptyTextImageUploadsThroughDecorator(t *testing.T) {// No doc_id in the payload (it would trigger the on-demand PDF crop path,// which needs a database), so the id hashes the empty document id plus the// captionless image's own identity (mediaChunkIdentity).- wantChunkID := common.ChunkID("", mediaChunkIdentity(payload, ""))+ wantChunkID := common.ChunkID("", mediaChunkIdentity(payload, "", nil))if ck["id"] != wantChunkID {t.Errorf("id = %v, want %q", ck["id"], wantChunkID)}diff --git a/internal/ingestion/component/chunker/token.go b/internal/ingestion/component/chunker/token.goindex 4cafa80311..b2b6113f9d 100644--- a/internal/ingestion/component/chunker/token.go+++ b/internal/ingestion/component/chunker/token.go@@ -271,11 +271,30 @@ func decodeChunkerFromUpstream(inputs map[string]any) (schema.ChunkerFromUpstreaif err := out.Validate(); err != nil {return out, err}+ if err := validateUpstreamMediaRefs(out.JSONResult); err != nil {+ return out, err+ }+ if err := validateUpstreamMediaRefs(out.Chunks); err != nil {+ return out, err+ }materializeTableText(out.JSONResult)materializeTableText(out.Chunks)return out, nil}+// validateUpstreamMediaRefs rejects any present but unusable reference at the+// chunker input boundary. Chunkers merge items and keep only the first media+// attachment, so validating when an item is consumed would make the failure+// depend on input order; every present reference must be checked first.+func validateUpstreamMediaRefs(items []schema.ChunkDoc) error {+ for i := range items {+ if ref := items[i].MediaRef; ref != nil && !ref.Valid() {+ return fmt.Errorf("chunker: item %d has an invalid media_ref", i)+ }+ }+ return nil+}+func stripChunkerRuntimeTimestamps(inputs map[string]any) map[string]any {out := make(map[string]any, len(inputs))for k, v := range inputs {@@ -664,8 +683,10 @@ func (c *TokenChunkerComponent) invokeJSONPayload(ctx context.Context, items []s// context_below) then .strip() — so a context that carries nothing but// a position tag counts as empty. The context is folded into Text once,// at chunkOutputs, so the decision is made on that merged text here- // without duplicating the fold.- if strings.TrimSpace(removeTag(schema.ContextualText(m))) == "" {+ // without duplicating the fold. Inline bytes, an uploaded ID or a+ // deferred reference also make the chunk retrievable; dropping it here+ // would lose the image before the materializer can resolve or reject it.+ if strings.TrimSpace(removeTag(schema.ContextualText(m))) == "" && !hasMediaPayload(m) {continue}materialized = append(materialized, materializeMediaContext(m))@@ -830,6 +851,7 @@ func buildChunkDoc(it schema.ChunkDoc, ckType, text, ctxAbove, ctxBelow string)PDFPositions: it.PDFPositions,Positions: it.Positions,Image: it.Image,+ MediaRef: it.MediaRef,PageNumber: it.PageNumber,Sheet: it.Sheet,SheetIndex: it.SheetIndex,diff --git a/internal/ingestion/component/media_dispatch.go b/internal/ingestion/component/media_dispatch.goindex ccca6ff1ea..f0b9334c75 100644--- a/internal/ingestion/component/media_dispatch.go+++ b/internal/ingestion/component/media_dispatch.go@@ -37,6 +37,7 @@ import (modelModule "ragflow/internal/entity/models""ragflow/internal/ingestion/component/progress""ragflow/internal/ingestion/component/schema"+ "ragflow/internal/parser/media""ragflow/internal/parser/parser""ragflow/internal/utility"@@ -108,7 +109,7 @@ func maybeDispatchImage(return parser.ParseResult{}, true, err}defer release()- if len(binary) == 0 || len(binary) > parser.MaxImagePayloadBytes {+ if len(binary) == 0 || len(binary) > media.MaxImagePayloadBytes {return parser.ParseResult{}, true, fmt.Errorf("parser: image payload exceeds size limits")}// SVG carries its text in the document, so it is read rather thandiff --git a/internal/ingestion/component/media_materialize.go b/internal/ingestion/component/media_materialize.gonew file mode 100644index 0000000000..46ee601105--- /dev/null+++ b/internal/ingestion/component/media_materialize.go@@ -0,0 +1,101 @@+// 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.++package component++import (+ "context"+ "encoding/base64"+ "errors"++ "ragflow/internal/entity"+ "ragflow/internal/parser/media"+)++// MaterializeMediaItem fills m["image"] from m["media_ref"] when the item+// carries a reference and no inline bytes. The item map is the parser/chunker+// wire shape, so the upload pass and vision enhancement share one seam.+func MaterializeMediaItem(ctx context.Context, m map[string]any) error {+ if m == nil {+ return nil+ }+ if img, _ := m["image"].(string); img != "" {+ return nil+ }+ data, ref, err := ResolveMediaRef(ctx, m)+ if err != nil || ref == nil {+ return err+ }+ m["image"] = encodeMediaDataURI(ref.MIME, data)+ return nil+}++// ResolveMediaRef reads the item's run-scoped media reference from the cache.+// It returns (nil, nil, nil) when no reference is present so callers can keep+// their existing inline-image path. A malformed reference, unsupported source+// kind, cache failure, or payload integrity failure is returned to the caller.+func ResolveMediaRef(ctx context.Context, m map[string]any) ([]byte, *entity.MediaRef, error) {+ if m == nil {+ return nil, nil, nil+ }+ ref := entity.MediaRefFromAny(m["media_ref"])+ if ref == nil {+ if mediaRefPresent(m["media_ref"]) {+ return nil, nil, errors.New("media: media_ref is present but has no usable format/kind/digest")+ }+ return nil, nil, nil+ }+ if ref.Kind != entity.MediaKindKV {+ return nil, nil, errors.New("media: only run-cache media references are supported")+ }+ cache := media.CacheFromContext(ctx)+ if cache == nil {+ return nil, nil, errors.New("media: reference present but no run cache")+ }+ data, err := cache.Get(ctx, *ref)+ if err != nil {+ return nil, nil, err+ }+ return data, ref, nil+}++// mediaRefPresent reports whether a media_ref value claims to be a reference.+// A nil pointer, zero value, empty string, or empty map is treated as absent;+// anything else that did not decode into a usable MediaRef is malformed.+func mediaRefPresent(v any) bool {+ switch ref := v.(type) {+ case nil:+ return false+ case *entity.MediaRef:+ return !ref.IsZero()+ case entity.MediaRef:+ return !ref.IsZero()+ case string:+ return ref != ""+ case map[string]any:+ return len(ref) > 0+ default:+ return true+ }+}++// encodeMediaDataURI renders image bytes in the form the chunker expects for+// upload and vision materialization. An empty MIME falls back to+// application/octet-stream; image references always carry a concrete type.+func encodeMediaDataURI(mime string, data []byte) string {+ if mime == "" {+ mime = "application/octet-stream"+ }+ return "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(data)+}diff --git a/internal/ingestion/component/media_materialize_test.go b/internal/ingestion/component/media_materialize_test.gonew file mode 100644index 0000000000..3905b31059--- /dev/null+++ b/internal/ingestion/component/media_materialize_test.go@@ -0,0 +1,162 @@+// 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.++package component++import (+ "context"+ "crypto/sha256"+ "encoding/base64"+ "encoding/hex"+ "errors"+ "strings"+ "testing"++ "ragflow/internal/entity"+ "ragflow/internal/parser/media"+)++type materializeCache struct {+ data []byte+ err error+ get int+}++func (c *materializeCache) Put(_ context.Context, format, mime string, data []byte) (entity.MediaRef, error) {+ if c.err != nil && !errors.Is(c.err, media.ErrMediaNotFound) {+ return entity.MediaRef{}, c.err+ }+ c.data = append([]byte(nil), data...)+ sum := sha256.Sum256(data)+ return entity.MediaRef{Format: format, Kind: entity.MediaKindKV, Scope: "run-1", SHA256: hex.EncodeToString(sum[:]), MIME: mime, Size: int64(len(data))}, nil+}++func (c *materializeCache) Get(_ context.Context, ref entity.MediaRef) ([]byte, error) {+ c.get+++ if c.err != nil {+ return nil, c.err+ }+ return media.ValidatePayload(c.data, ref)+}++func cacheMediaRef() entity.MediaRef {+ sum := sha256.Sum256([]byte("hello"))+ return entity.MediaRef{+ Format: "html",+ Kind: entity.MediaKindKV,+ Scope: "run-1",+ SHA256: hex.EncodeToString(sum[:]),+ MIME: "image/png",+ Size: 5,+ }+}++func TestResolveMediaRefReturnsDecodedCacheBytes(t *testing.T) {+ cache := &materializeCache{data: []byte("hello")}+ ctx := media.WithCache(context.Background(), cache)+ data, ref, err := ResolveMediaRef(ctx, map[string]any{"media_ref": cacheMediaRef()})+ if err != nil {+ t.Fatalf("ResolveMediaRef: %v", err)+ }+ if ref == nil || ref.Kind != entity.MediaKindKV || string(data) != "hello" {+ t.Fatalf("ResolveMediaRef = ref %+v, data %q", ref, data)+ }+}++func TestResolveMediaRefRejectsUnsupportedKindAndCorruptBytes(t *testing.T) {+ supported := cacheMediaRef()+ unsupported := supported+ unsupported.Kind = "data-uri"+ ctx := media.WithCache(context.Background(), &materializeCache{data: []byte("hello")})+ if _, _, err := ResolveMediaRef(ctx, map[string]any{"media_ref": unsupported}); err == nil {+ t.Fatal("ResolveMediaRef accepted the removed data-uri source path")+ }++ ctx = media.WithCache(context.Background(), &materializeCache{data: []byte("HELLO")})+ if _, _, err := ResolveMediaRef(ctx, map[string]any{"media_ref": supported}); err == nil {+ t.Fatal("ResolveMediaRef accepted bytes that do not match the reference")+ }+}++func TestMaterializeMediaItemUsesRunCache(t *testing.T) {+ cache := &materializeCache{data: []byte("hello")}+ ctx := media.WithCache(context.Background(), cache)+ ref := cacheMediaRef()+ m := map[string]any{"media_ref": ref}+ if err := MaterializeMediaItem(ctx, m); err != nil {+ t.Fatalf("MaterializeMediaItem: %v", err)+ }+ if cache.get != 1 {+ t.Fatalf("cache Get calls = %d, want 1", cache.get)+ }+ want := "data:image/png;base64," + base64.StdEncoding.EncodeToString([]byte("hello"))+ if m["image"] != want {+ t.Fatalf("image = %v, want %q", m["image"], want)+ }+}++func TestMaterializeMediaItemPropagatesCacheMiss(t *testing.T) {+ cache := &materializeCache{err: media.ErrMediaNotFound}+ ctx := media.WithCache(context.Background(), cache)+ m := map[string]any{"media_ref": cacheMediaRef()}+ if err := MaterializeMediaItem(ctx, m); !errors.Is(err, media.ErrMediaNotFound) {+ t.Fatalf("MaterializeMediaItem error = %v, want cache miss", err)+ }+}++func TestEncodeMediaDataURIRoundTrip(t *testing.T) {+ data := []byte("hello world")+ uri := encodeMediaDataURI("image/png", data)+ const prefix = "data:image/png;base64,"+ if !strings.HasPrefix(uri, prefix) {+ t.Fatalf("uri = %q", uri)+ }+ decoded, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(uri, prefix))+ if err != nil {+ t.Fatalf("decode: %v", err)+ }+ if string(decoded) != string(data) {+ t.Fatalf("decoded = %q, want %q", decoded, data)+ }+}++func TestMaterializeMediaItemRejectsInvalidMediaRef(t *testing.T) {+ m := map[string]any{"media_ref": map[string]any{"format": "html"}}+ if err := MaterializeMediaItem(context.Background(), m); err == nil {+ t.Fatal("a present but unusable media_ref was treated as absent")+ }+}++func TestMaterializeMediaItemTreatsAbsentMediaRefAsNoop(t *testing.T) {+ var nilRef *entity.MediaRef+ zero := &entity.MediaRef{}+ for _, value := range []any{nil, "", map[string]any{}, nilRef, zero, entity.MediaRef{}} {+ m := map[string]any{"media_ref": value}+ if err := MaterializeMediaItem(context.Background(), m); err != nil {+ t.Errorf("media_ref %#v: %v", value, err)+ }+ }+}++func TestMaterializeMediaItemRequiresRunCacheForPresentRef(t *testing.T) {+ m := map[string]any{"media_ref": map[string]any{+ "format": "html",+ "kind": "kvrocks",+ "scope": "run-1",+ "sha256": strings.Repeat("a", 64),+ }}+ if err := MaterializeMediaItem(context.Background(), m); err == nil {+ t.Fatal("a present reference without a run cache was treated as absent")+ }+}diff --git a/internal/ingestion/component/parser.go b/internal/ingestion/component/parser.goindex 8b5c220e32..a262a9d56b 100644--- a/internal/ingestion/component/parser.go+++ b/internal/ingestion/component/parser.go@@ -545,7 +545,11 @@ func (c *ParserComponent) Invoke(ctx context.Context, db *gorm.DB, inputs map[st}if enhanceOn && !handledMedia && !handledImage && !handledAudio && dispatched.Err == nil && ctx.Err() == nil {// PDF dispatch and ordinary parsers share enhancement after normalization.- dispatched, _, _ = maybeDispatchVisionEnhancement(ctx, db, fileTypeExt, dispatched, inputs, c.vision, visionWin)+ var enhanceErr error+ dispatched, _, enhanceErr = maybeDispatchVisionEnhancement(ctx, db, fileTypeExt, dispatched, inputs, c.vision, visionWin)+ if enhanceErr != nil {+ return nil, enhanceErr+ }} else {// Enhancement skipped entirely (disabled or non-PDF media handled):// still strip the transient backend-description marker so it neverdiff --git a/internal/ingestion/component/schema/chunk_media_ref_test.go b/internal/ingestion/component/schema/chunk_media_ref_test.gonew file mode 100644index 0000000000..5cd4e6523b--- /dev/null+++ b/internal/ingestion/component/schema/chunk_media_ref_test.go@@ -0,0 +1,112 @@+// 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.++package schema++import (+ "strings"+ "testing"++ "ragflow/internal/entity"+)++func TestChunkDocMediaRefRoundTrip(t *testing.T) {+ ref := &entity.MediaRef{+ Format: "html",+ Kind: entity.MediaKindKV,+ Scope: "run-1",+ SHA256: strings.Repeat("a", 64),+ MIME: "image/png",+ Size: 5,+ }+ doc, err := ChunkDocFromMap(map[string]any{+ "text": "",+ "doc_type_kwd": "image",+ "media_ref": ref,+ })+ if err != nil {+ t.Fatalf("ChunkDocFromMap: %v", err)+ }+ if doc.MediaRef == nil || doc.MediaRef.SHA256 != ref.SHA256 {+ t.Fatalf("media_ref lost in decode: %+v", doc.MediaRef)+ }+ if _, ok := doc.Extra["media_ref"]; ok {+ t.Fatal("media_ref leaked into Extra")+ }+ got := entity.MediaRefFromAny(doc.ToMap()["media_ref"])+ if got == nil || got.SHA256 != ref.SHA256 || got.Format != "html" || got.Kind != entity.MediaKindKV || got.Scope != "run-1" {+ t.Fatalf("media_ref lost in encode: %+v", doc.ToMap()["media_ref"])+ }+}++func TestChunkDocEmptyMediaRefNormalizesToNil(t *testing.T) {+ doc, err := ChunkDocFromMap(map[string]any{+ "text": "x",+ "media_ref": map[string]any{},+ })+ if err != nil {+ t.Fatalf("ChunkDocFromMap: %v", err)+ }+ if doc.MediaRef != nil {+ t.Fatalf("empty media_ref survived as %+v", doc.MediaRef)+ }+ if _, ok := doc.ToMap()["media_ref"]; ok {+ t.Fatal("empty media_ref reappeared on the wire")+ }+}++func TestChunkDocUnknownMediaRefFieldsFail(t *testing.T) {+ for _, tc := range []struct {+ name string+ raw map[string]any+ }{+ {"unknown only", map[string]any{"unknown": "value"}},+ {"empty known field", map[string]any{"format": ""}},+ } {+ t.Run(tc.name, func(t *testing.T) {+ if _, err := ChunkDocFromMap(map[string]any{+ "text": "x",+ "media_ref": tc.raw,+ }); err == nil {+ t.Fatal("malformed media_ref was normalized away")+ }+ })+ }+}++func TestChunkDocNullMediaRefNormalizesToNil(t *testing.T) {+ doc, err := ChunkDocFromMap(map[string]any{+ "text": "x",+ "media_ref": nil,+ })+ if err != nil {+ t.Fatalf("ChunkDocFromMap: %v", err)+ }+ if doc.MediaRef != nil {+ t.Fatalf("null media_ref survived as %+v", doc.MediaRef)+ }+}++func TestChunkDocPartialMediaRefSurvives(t *testing.T) {+ doc, err := ChunkDocFromMap(map[string]any{+ "text": "x",+ "media_ref": map[string]any{"format": "html"},+ })+ if err != nil {+ t.Fatalf("ChunkDocFromMap: %v", err)+ }+ if doc.MediaRef == nil {+ t.Fatal("partially filled media_ref was normalized away")+ }+}diff --git a/internal/ingestion/component/schema/chunk_types.go b/internal/ingestion/component/schema/chunk_types.goindex ad631378a4..30354dc24e 100644--- a/internal/ingestion/component/schema/chunk_types.go+++ b/internal/ingestion/component/schema/chunk_types.go@@ -18,6 +18,8 @@ package schemaimport ("encoding/json"+ "errors"+ "fmt""ragflow/internal/entity""ragflow/internal/parser/parser"@@ -137,8 +139,12 @@ type ChunkDoc struct {// the table content is consumed directly from here instead of being// re-parsed from Text markup. It must stay out of Extra (see the// deletion list in UnmarshalJSON).- TableData *entity.TableData `json:"table,omitempty"`- Extra map[string]json.RawMessage `json:"-"`+ TableData *entity.TableData `json:"table,omitempty"`+ // MediaRef points at the image in the run-scoped media cache. Image carries+ // bytes only for formats that still inline; otherwise the chunker+ // materializes the reference before upload.+ MediaRef *entity.MediaRef `json:"media_ref,omitempty"`+ Extra map[string]json.RawMessage `json:"-"`}func (d *ChunkDoc) UnmarshalJSON(data []byte) error {@@ -151,13 +157,17 @@ func (d *ChunkDoc) UnmarshalJSON(data []byte) error {if err := json.Unmarshal(data, &raw); err != nil {return err}+ // Keep the reference before the known-field deletion pass: the typed+ // decode discards unknown keys, so the raw object is the only place an+ // empty reference and a malformed one can be told apart.+ mediaRefRaw := raw["media_ref"]// Known ChunkDoc fields plus tag_kwd, which has no ChunkDoc field: Go's// tagger emits tag_feas and the vocabulary comes from a tag source file,// so no chunk carries tag_kwd. Deleted rather than left in raw so it// cannot fall through to Extra and be re-emitted by MarshalJSON.for _, key := range []string{"text", "doc_type_kwd", "mom", "img_id",- "tk_nums", "layout", "layout_type", "layoutno", "image",+ "tk_nums", "layout", "layout_type", "layoutno", "image", "media_ref","context_above", "context_below", "questions", "keywords", "summary","chunk_order_int", "title_tks", "title_sm_tks", "content_ltks","content_sm_ltks", "tag_kwd", "page_number", "top_int", "_pdf_positions", "positions",@@ -166,12 +176,40 @@ func (d *ChunkDoc) UnmarshalJSON(data []byte) error {delete(raw, key)}*d = ChunkDoc(decoded)+ // A JSON `media_ref: {}` decodes into a non-nil zero value. Normalize it+ // back to nil so an empty object keeps meaning "no reference"; partially+ // filled references stay and are rejected by the materializer. A+ // non-empty object that decodes to the zero value named no recognized+ // field, and dropping it would let a malformed reference through.+ if d.MediaRef.IsZero() {+ if err := validateEmptyMediaRef(mediaRefRaw); err != nil {+ return err+ }+ d.MediaRef = nil+ }if len(raw) > 0 {d.Extra = raw}return nil}+// validateEmptyMediaRef accepts the forms that legitimately mean "no+// reference" (absent, null, or `{}`) and rejects an object whose keys are all+// unknown to MediaRef.+func validateEmptyMediaRef(raw json.RawMessage) error {+ if len(raw) == 0 {+ return nil+ }+ var fields map[string]json.RawMessage+ if err := json.Unmarshal(raw, &fields); err != nil {+ return fmt.Errorf("chunk media_ref: %w", err)+ }+ if len(fields) > 0 {+ return errors.New("chunk media_ref: object has no recognized fields")+ }+ return nil+}+func (d ChunkDoc) MarshalJSON() ([]byte, error) {// Delegate to wireMap so the typed []ChunkDoc form and the []map[string]any// wire form (ToMap / ChunkDocsToMaps) serialize identically by construction.diff --git a/internal/ingestion/component/svg_text.go b/internal/ingestion/component/svg_text.goindex 7e6df69691..6fde5604b1 100644--- a/internal/ingestion/component/svg_text.go+++ b/internal/ingestion/component/svg_text.go@@ -35,7 +35,7 @@ import (htmlcharset "golang.org/x/net/html/charset"- "ragflow/internal/parser/parser"+ "ragflow/internal/parser/media")// maxSVGDepth bounds element nesting: the XML decoder keeps one stack entry@@ -117,7 +117,7 @@ func extractSVGText(ctx context.Context, data []byte) (string, error) {value := string(match[2]) + string(match[3])references := bytes.Count(data, []byte("&"+string(match[1])+";"))expansion += int64(references) * int64(len(value))- if expansion > parser.MaxImagePayloadBytes {+ if expansion > media.MaxImagePayloadBytes {return "", errors.New("parser: decode SVG: entity expansion exceeds size limits")}entities[string(match[1])] = valuediff --git a/internal/ingestion/component/vision_config_test.go b/internal/ingestion/component/vision_config_test.goindex 505d3110b2..0e170bb3d9 100644--- a/internal/ingestion/component/vision_config_test.go+++ b/internal/ingestion/component/vision_config_test.go@@ -10,6 +10,7 @@ import (deepdoctype "ragflow/internal/deepdoc/parser/type""ragflow/internal/entity"modelModule "ragflow/internal/entity/models"+ "ragflow/internal/parser/media""ragflow/internal/parser/parser")@@ -58,7 +59,8 @@ func TestParserGlobalVisionModel(t *testing.T) {filename = "figure.html"binary = []byte(`<p><img src="data:image/png;base64,` + visionTestPNGBase64(t) + `" alt="figure"></p>`)}- result, err := component.Invoke(t.Context(), nil, map[string]any{"name": filename, "file_type": fileType, "binary": binary, "tenant_id": "tenant-1"})+ ctx := media.WithCache(t.Context(), &materializeCache{data: picturePNG(t)})+ result, err := component.Invoke(ctx, nil, map[string]any{"name": filename, "file_type": fileType, "binary": binary, "tenant_id": "tenant-1"})if err != nil {t.Fatal(err)}diff --git a/internal/ingestion/component/vision_enhancement.go b/internal/ingestion/component/vision_enhancement.goindex 305be7bd4c..b246bd5e62 100644--- a/internal/ingestion/component/vision_enhancement.go+++ b/internal/ingestion/component/vision_enhancement.go@@ -176,7 +176,9 @@ type visionImage struct {// maybeDispatchVisionEnhancement appends VLM descriptions to parsed image// resources and table regions. PDF OCR remains in the PDF parser; non-PDF-// image text comes from this optional enhancement.+// image text comes from this optional enhancement. It is best-effort per+// item: a failed image is counted in a warning and the rest of the parse+// result is still returned.// Mirrors Python's enhance_media_sections_with_vision in rag/flow/parser/utils.py:162.func maybeDispatchVisionEnhancement(ctx context.Context,@@ -216,6 +218,10 @@ func maybeDispatchVisionEnhancement(items = append(items, i)continue}+ if entity.MediaRefFromAny(m["media_ref"]) != nil {+ items = append(items, i)+ continue+ }kd, _ := m["doc_type_kwd"].(string)if kd == "image" || kd == "table" {// A page-only position carries no crop region, so it must not@@ -282,6 +288,7 @@ func maybeDispatchVisionEnhancement(modified := falsedescriptions := make([]string, len(items))failures := make([]string, len(items))+ mediaFailures := make([]error, len(items))var wg sync.WaitGroupsem := make(chan struct{}, visionEnhancementConcurrency)var settled atomic.Int64@@ -306,7 +313,9 @@ func maybeDispatchVisionEnhancement(}var resource *visionImagefunc() {- item := dispatched.JSON[itemIdx].ToMap()+ // Clone before materializing: RawItem.ToMap returns the shared+ // map, and filling in image bytes must not mutate the parse result.+ item := maps.Clone(dispatched.JSON[itemIdx].ToMap())if err := cropper.Prepare(ctx, item); err != nil {if ctx.Err() == nil {if payload, _ := item["image"].(string); isUsableVisionImage(payload) {@@ -334,6 +343,13 @@ func maybeDispatchVisionEnhancement(return}defer release()+ // Materialize under the same admission as the crop: the decode+ // and re-encode of a deferred image must not bypass the shared+ // image memory limit.+ if err := MaterializeMediaItem(itemCtx, item); err != nil {+ mediaFailures[slot] = err+ return+ }resource, err = cropper.Crop(itemCtx, item)if err != nil || resource == nil {cropErr := err@@ -415,6 +431,11 @@ func maybeDispatchVisionEnhancement(if err := ctx.Err(); err != nil {return stripBackendDescribedResult(dispatched), modified, err}+ for _, err := range mediaFailures {+ if err != nil {+ return stripBackendDescribedResult(dispatched), modified, fmt.Errorf("vision enhancement: materialize media: %w", err)+ }+ }w.Report(ctx, 1.0)failedItems := 0firstFailure := ""diff --git a/internal/ingestion/component/vision_enhancement_test.go b/internal/ingestion/component/vision_enhancement_test.goindex d94b2eed9e..3b5b602f89 100644--- a/internal/ingestion/component/vision_enhancement_test.go+++ b/internal/ingestion/component/vision_enhancement_test.go@@ -37,6 +37,7 @@ import (modelModule "ragflow/internal/entity/models""ragflow/internal/ingestion/component/progress""ragflow/internal/ingestion/component/schema"+ "ragflow/internal/parser/media""ragflow/internal/parser/parser""ragflow/internal/utility"@@ -174,12 +175,13 @@ func TestParserComponent_VisionEnhancementSwitchGatesEmbeddedImage(t *testing.T)"tenant_id": "tenant-1",}}+ ctx := media.WithCache(t.Context(), &materializeCache{data: picturePNG(t)})defaultComponent, err := NewParserComponent(nil)if err != nil {t.Fatalf("NewParserComponent(nil): %v", err)}- withoutVision, err := defaultComponent.Invoke(t.Context(), nil, inputs())+ withoutVision, err := defaultComponent.Invoke(ctx, nil, inputs())if err != nil {t.Fatalf("default Invoke: %v", err)}@@ -196,7 +198,7 @@ func TestParserComponent_VisionEnhancementSwitchGatesEmbeddedImage(t *testing.T)if err != nil {t.Fatalf("NewParserComponent(enabled): %v", err)}- withVision, err := enabledComponent.Invoke(t.Context(), nil, inputs())+ withVision, err := enabledComponent.Invoke(ctx, nil, inputs())if err != nil {t.Fatalf("enabled Invoke: %v", err)}@@ -215,6 +217,71 @@ func TestParserComponent_VisionEnhancementSwitchGatesEmbeddedImage(t *testing.T)}}+func TestVisionEnhancement_MaterializesMediaRef(t *testing.T) {+ invoker := &visionEnhanceCaptureInvoker{}+ swapVisionGlobals(t, fakeResolver, invoker.invoke, fakePrompt)++ uri := "data:image/png;base64," + visionTestPNGBase64(t)+ html := `<p><img alt="figure" src="` + uri + `"></p>`+ imageBytes, err := base64.StdEncoding.DecodeString(visionTestPNGBase64(t))+ if err != nil {+ t.Fatal(err)+ }+ cache := &materializeCache{data: imageBytes}+ ctx := media.WithCache(t.Context(), cache)+ p := parser.NewHTMLParser()+ parsed := p.ParseWithResult(ctx, "ref.html", []byte(html))+ if parsed.Err != nil {+ t.Fatal(parsed.Err)+ }+ if _, ok := parsed.JSON[0].ToMap()["image"]; ok {+ t.Fatal("parser retained image bytes")+ }++ res, handled, err := maybeDispatchVisionEnhancement(+ ctx, dao.DB, utility.FileTypeHTML, parsed,+ map[string]any{"tenant_id": "t1"},+ visionSettings{}, progress.Window{})+ if err != nil {+ t.Fatalf("maybeDispatchVisionEnhancement: %v", err)+ }+ if !handled {+ t.Fatal("handled = false, want true")+ }+ if len(invoker.images) != 1 {+ t.Fatalf("VLM calls = %d, want 1", len(invoker.images))+ }+ text, _ := res.JSON[0].ToMap()["text"].(string)+ if !strings.Contains(text, "a diagram of a pipeline") {+ t.Fatalf("enhanced text = %q, missing the VLM description", text)+ }+}++func TestVisionEnhancement_MediaCacheMissFailsTask(t *testing.T) {+ invoker := &visionEnhanceCaptureInvoker{}+ swapVisionGlobals(t, fakeResolver, invoker.invoke, fakePrompt)++ cache := &materializeCache{err: media.ErrMediaNotFound}+ ctx := media.WithCache(t.Context(), cache)+ dispatched := parser.ParseResult{+ JSON: parser.MapsToItems([]map[string]any{{+ "text": "figure",+ "doc_type_kwd": "image",+ "media_ref": cacheMediaRef(),+ }}),+ }+ _, _, err := maybeDispatchVisionEnhancement(+ ctx, dao.DB, utility.FileTypeHTML, dispatched,+ map[string]any{"tenant_id": "t1"},+ visionSettings{}, progress.Window{})+ if !errors.Is(err, media.ErrMediaNotFound) {+ t.Fatalf("maybeDispatchVisionEnhancement error = %v, want cache miss", err)+ }+ if len(invoker.images) != 0 {+ t.Fatalf("VLM calls = %d, want none after cache miss", len(invoker.images))+ }+}+func TestVisionEnhancement_AppendsVLMToExistingText(t *testing.T) {invoker := &visionEnhanceCaptureInvoker{}swapVisionGlobals(t, fakeResolver, invoker.invoke, fakePrompt)@@ -1231,3 +1298,21 @@ func TestDefaultVisionChatInvoker_AppliesDeadline(t *testing.T) {t.Fatal("non-Ollama vision chat must preserve provider thinking default")}}++func TestParserComponent_VisionMediaCacheMissFails(t *testing.T) {+ invoker := &visionEnhanceCaptureInvoker{}+ swapVisionGlobals(t, fakeResolver, invoker.invoke, fakePrompt)+ cache := &materializeCache{err: media.ErrMediaNotFound}+ ctx := media.WithCache(t.Context(), cache)+ component, err := NewParserComponent(map[string]any{"enable_vision_enhancement": true})+ if err != nil {+ t.Fatal(err)+ }+ _, err = component.Invoke(ctx, nil, map[string]any{+ "binary": []byte(`<img alt="figure" src="data:image/png;base64,` + visionTestPNGBase64(t) + `">`),+ "file_type": "html", "name": "figure.html", "tenant_id": "tenant-1",+ })+ if !errors.Is(err, media.ErrMediaNotFound) {+ t.Fatalf("Invoke error = %v, want cache miss", err)+ }+}diff --git a/internal/ingestion/component/vision_image.go b/internal/ingestion/component/vision_image.goindex dd14c0a2a1..f304dd6372 100644--- a/internal/ingestion/component/vision_image.go+++ b/internal/ingestion/component/vision_image.go@@ -31,11 +31,12 @@ import (_ "image/gif"_ "image/jpeg"+ "ragflow/internal/parser/media"parserlib "ragflow/internal/parser/parser")const (- maxVisionImageBytes = parserlib.MaxImagePayloadBytes+ maxVisionImageBytes = media.MaxImagePayloadBytesmaxVLMEncodedBytes = (maxVisionImageBytes+2)/3*4 + 256// maxVLMCropPixels and maxVLMCropEdge bound the raster of PDF page crops// rendered for the vision model (see vision_enhancement_cgo.go). They are adiff --git a/internal/ingestion/deps.go b/internal/ingestion/deps.goindex fcc9400ed2..5e187a64f4 100644--- a/internal/ingestion/deps.go+++ b/internal/ingestion/deps.go@@ -37,10 +37,9 @@ import (// constructed once per process at the assembly point and threaded through the// Ingestor, TaskContext, PipelineExecutor, and the knowledge-compile Consumer.//-// KV is optional: a nil client disables the chunkcache and the memory id-// generator, which fall back to their documented no-cache / local-id paths.-// Engine, DB, and MQ are required for a production run; Validate reports the-// missing ones at startup instead of failing mid-task.+// Engine, DB, MQ and KV are required for a production ingestor. HTML+// ingestion uses KV to hand decoded images to downstream components, so+// Validate reports a missing client at startup.type Deps struct {// Engine persists and searches chunks (document index, memory messages,// compiled knowledge products).@@ -50,13 +49,11 @@ type Deps struct {DB *gorm.DB// MQ is the task broker (NATS JetStream) the ingestor consumes.MQ engine.MessageQueue- // KV is the kvrocks client (chunkcache, run trackers, memory ids). nil- // disables those optional accelerators.+ // KV is the Kvrocks client for HTML media, chunkcache, run trackers and memory ids.KV *kvrocks.Client}-// Validate reports the required dependencies that are missing. KV is allowed-// to be nil (optional accelerator); Engine, DB, and MQ are not.+// Validate reports the required production ingestor dependencies that are missing.func (d *Deps) Validate() error {if d == nil {return fmt.Errorf("ingestion deps: nil dependency bundle")@@ -71,6 +68,9 @@ func (d *Deps) Validate() error {if d.MQ == nil {missing = append(missing, "message queue")}+ if d.KV == nil || d.KV.GetClient() == nil {+ missing = append(missing, "kvrocks")+ }if len(missing) > 0 {return fmt.Errorf("ingestion deps: missing required dependencies: %v", missing)}diff --git a/internal/ingestion/mediacache/store.go b/internal/ingestion/mediacache/store.gonew file mode 100644index 0000000000..69ff9a38c5--- /dev/null+++ b/internal/ingestion/mediacache/store.go@@ -0,0 +1,201 @@+// 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.++// Package mediacache stores decoded parser media for the short-lived,+// run-scoped handoff between Parser, vision enhancement and Chunker. It uses+// an independent one-day TTL and media manifest; persistence success purges+// media through that manifest.+package mediacache++import (+ "context"+ "crypto/sha256"+ "encoding/hex"+ "errors"+ "fmt"+ "strings"+ "sync"+ "time"++ "github.com/cespare/xxhash/v2"++ "ragflow/internal/entity"+ "ragflow/internal/ingestion/chunkcache"+ "ragflow/internal/ingestion/component/globals"+ "ragflow/internal/parser/media"+)++const (+ keyNamespace = "mc"+ TTL = 24 * time.Hour+)++// Store is a run-scoped media cache backed by a chunkcache.Store.+type Store struct {+ backend chunkcache.Store+ scope string++ mu sync.Mutex+}++// New returns a cache bound to one ingestion run. A nil backend is a valid+// value so callers can surface configured-cache failures only when media is+// actually encountered.+func New(backend chunkcache.Store, scope string) *Store {+ return &Store{+ backend: backend,+ scope: strings.TrimSpace(scope),+ }+}++// Put validates and stores one decoded image, then records the key on the+// current task manifest. Any write or lifecycle failure is returned.+func (s *Store) Put(ctx context.Context, format, mime string, data []byte) (entity.MediaRef, error) {+ if s == nil || s.backend == nil {+ return entity.MediaRef{}, errors.New("mediacache: cache is not configured")+ }+ if s.scope == "" {+ return entity.MediaRef{}, errors.New("mediacache: run scope is empty")+ }+ if taskID := globals.TaskID(ctx); taskID != "" && taskID != s.scope {+ return entity.MediaRef{}, fmt.Errorf("mediacache: run scope %q does not match task %q", s.scope, taskID)+ }+ if strings.TrimSpace(format) == "" {+ return entity.MediaRef{}, errors.New("mediacache: media format is empty")+ }+ if strings.TrimSpace(mime) == "" {+ return entity.MediaRef{}, errors.New("mediacache: media type is empty")+ }+ if len(data) == 0 || len(data) > media.HTMLImageMaxBytes() {+ return entity.MediaRef{}, fmt.Errorf("mediacache: image size %d is outside the 1..%d-byte limit", len(data), media.HTMLImageMaxBytes())+ }++ sum := sha256.Sum256(data)+ digest := hex.EncodeToString(sum[:])+ ref := entity.MediaRef{+ Format: format,+ Kind: entity.MediaKindKV,+ Scope: s.scope,+ SHA256: digest,+ MIME: strings.ToLower(strings.TrimSpace(mime)),+ Size: int64(len(data)),+ }++ s.mu.Lock()+ defer s.mu.Unlock()++ key := s.key(digest)+ if !s.backend.Set(ctx, key, string(data), TTL) {+ return entity.MediaRef{}, fmt.Errorf("mediacache: write image %s", mediaShortDigest(digest))+ }+ if err := s.track(ctx, key); err != nil {+ if !s.backend.Delete(ctx, key) {+ return entity.MediaRef{}, fmt.Errorf("mediacache: track image %s: %w (rollback failed)", mediaShortDigest(digest), err)+ }+ return entity.MediaRef{}, fmt.Errorf("mediacache: track image %s: %w", mediaShortDigest(digest), err)+ }+ return ref, nil+}++// Get resolves a reference and validates its scope, digest and encoded size.+// A cache miss is media.ErrMediaNotFound; backend and corruption failures are+// distinct errors so callers cannot silently turn them into a skipped image.+func (s *Store) Get(ctx context.Context, ref entity.MediaRef) ([]byte, error) {+ if err := ctx.Err(); err != nil {+ return nil, err+ }+ if s == nil || s.backend == nil {+ return nil, errors.New("mediacache: cache is not configured")+ }+ if s.scope == "" {+ return nil, errors.New("mediacache: run scope is empty")+ }+ if taskID := globals.TaskID(ctx); taskID != "" && taskID != s.scope {+ return nil, fmt.Errorf("mediacache: run scope %q does not match task %q", s.scope, taskID)+ }+ if !ref.Valid() || ref.Kind != entity.MediaKindKV {+ return nil, errors.New("mediacache: invalid kvrocks media reference")+ }+ if ref.Scope != s.scope {+ return nil, fmt.Errorf("mediacache: reference scope %q does not match run scope %q", ref.Scope, s.scope)+ }+ if ref.Size > int64(media.HTMLImageMaxBytes()) {+ return nil, fmt.Errorf("mediacache: image %s exceeds the %d-byte limit", mediaShortDigest(ref.SHA256), media.HTMLImageMaxBytes())+ }++ value, err := s.backend.Get(ctx, s.key(ref.SHA256))+ if err != nil {+ return nil, fmt.Errorf("mediacache: read image %s: %w", mediaShortDigest(ref.SHA256), err)+ }+ if value == "" {+ return nil, fmt.Errorf("%w: image %s", media.ErrMediaNotFound, mediaShortDigest(ref.SHA256))+ }+ data, err := media.ValidatePayload([]byte(value), ref)+ if err != nil {+ return nil, fmt.Errorf("mediacache: validate image %s: %w", mediaShortDigest(ref.SHA256), err)+ }+ return data, nil+}++func (s *Store) key(digest string) string {+ return fmt.Sprintf("%s:media:%x:%s", keyNamespace, xxhash.Sum64String(s.scope), digest)+}++func mediaShortDigest(digest string) string {+ if len(digest) <= 12 {+ return digest+ }+ return digest[:12]+}++func manifestKey(scope string) string {+ return fmt.Sprintf("%s:manifest:%x", keyNamespace, xxhash.Sum64String(scope))+}++func (s *Store) track(ctx context.Context, key string) error {+ // Taskless preview runs have no persist-time cleanup and rely on TTL.+ if globals.TaskID(ctx) == "" {+ return nil+ }+ mk := manifestKey(s.scope)+ if !s.backend.SAdd(ctx, mk, key) {+ return fmt.Errorf("mediacache: record manifest %s", mk)+ }+ if !s.backend.Expire(ctx, mk, TTL) {+ s.backend.Delete(ctx, mk)+ return fmt.Errorf("mediacache: expire manifest %s", mk)+ }+ return nil+}++// PurgeTask removes media after durable persistence. Failed runs rely on TTL.+func PurgeTask(ctx context.Context, backend chunkcache.Store, taskID string) error {+ if backend == nil || taskID == "" {+ return nil+ }+ mk := manifestKey(taskID)+ keys, err := backend.SMembers(ctx, mk)+ if err != nil {+ return fmt.Errorf("mediacache: read manifest: %w", err)+ }+ for _, key := range keys {+ if !backend.Delete(ctx, key) {+ return fmt.Errorf("mediacache: delete %s", key)+ }+ }+ if !backend.Delete(ctx, mk) {+ return fmt.Errorf("mediacache: delete manifest %s", mk)+ }+ return nil+}diff --git a/internal/ingestion/mediacache/store_test.go b/internal/ingestion/mediacache/store_test.gonew file mode 100644index 0000000000..0a1b34166e--- /dev/null+++ b/internal/ingestion/mediacache/store_test.go@@ -0,0 +1,402 @@+// 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.++package mediacache++import (+ "context"+ "errors"+ "fmt"+ "sort"+ "strings"+ "testing"+ "time"++ "ragflow/internal/agent/runtime"+ "ragflow/internal/entity"+ "ragflow/internal/ingestion/component/globals"+ "ragflow/internal/parser/media"+)++type fakeStore struct {+ kv map[string]string+ sets map[string]map[string]bool+ ttl map[string]time.Duration+ getErr error+ failSet bool+ expireFails bool+ setCalls int+ addCalls int+ deleteFails map[string]bool+}++func newFakeStore() *fakeStore {+ return &fakeStore{+ kv: map[string]string{},+ sets: map[string]map[string]bool{},+ ttl: map[string]time.Duration{},+ }+}++func (f *fakeStore) Get(_ context.Context, key string) (string, error) {+ if f.getErr != nil {+ return "", f.getErr+ }+ return f.kv[key], nil+}++func (f *fakeStore) Set(_ context.Context, key, value string, exp time.Duration) bool {+ f.setCalls+++ if f.failSet {+ return false+ }+ f.kv[key] = value+ f.ttl[key] = exp+ return true+}++func (f *fakeStore) SAdd(_ context.Context, key, member string) bool {+ f.addCalls+++ if f.sets[key] == nil {+ f.sets[key] = map[string]bool{}+ }+ f.sets[key][member] = true+ return true+}++func (f *fakeStore) SMembers(_ context.Context, key string) ([]string, error) {+ out := make([]string, 0, len(f.sets[key]))+ for member := range f.sets[key] {+ out = append(out, member)+ }+ sort.Strings(out)+ return out, nil+}++func (f *fakeStore) Delete(_ context.Context, key string) bool {+ if f.deleteFails[key] {+ return false+ }+ delete(f.kv, key)+ delete(f.sets, key)+ return true+}++func (f *fakeStore) Expire(_ context.Context, key string, exp time.Duration) bool {+ if f.expireFails {+ return false+ }+ f.ttl[key] = exp+ return true+}++func taskContext(taskID string) context.Context {+ state := runtime.NewCanvasState("", "")+ ctx := runtime.WithState(context.Background(), state)+ globals.SetTaskID(ctx, taskID)+ return ctx+}++func TestPutAndGet_RoundTripAcrossRepeatedReads(t *testing.T) {+ backend := newFakeStore()+ store := New(backend, "task-1")+ ctx := taskContext("task-1")+ data := []byte("hello")++ ref, err := store.Put(ctx, "html", "image/png", data)+ if err != nil {+ t.Fatalf("Put: %v", err)+ }+ if ref.Format != "html" || ref.Kind != entity.MediaKindKV || ref.Scope != "task-1" || ref.MIME != "image/png" || ref.Size != int64(len(data)) {+ t.Fatalf("ref = %+v", ref)+ }+ if len(backend.kv) != 1 {+ t.Fatalf("cached keys = %v, want one", backend.kv)+ }+ var key string+ for k := range backend.kv {+ key = k+ if backend.ttl[k] != TTL {+ t.Errorf("cached TTL = %v, want %v", backend.ttl[k], TTL)+ }+ }+ members, _ := backend.SMembers(ctx, manifestKey("task-1"))+ if len(members) != 1 || members[0] != key {+ t.Fatalf("manifest = %v, want [%s]", members, key)+ }++ for attempt := 0; attempt < 2; attempt++ {+ got, err := store.Get(ctx, ref)+ if err != nil {+ t.Fatalf("Get #%d: %v", attempt+1, err)+ }+ if string(got) != string(data) {+ t.Fatalf("Get #%d = %q, want %q", attempt+1, got, data)+ }+ }+}++func TestGet_MissingIsNotTreatedAsSuccess(t *testing.T) {+ backend := newFakeStore()+ store := New(backend, "task-1")+ ctx := taskContext("task-1")+ ref, err := store.Put(ctx, "html", "image/png", []byte("hello"))+ if err != nil {+ t.Fatal(err)+ }+ for key := range backend.kv {+ delete(backend.kv, key)+ }++ if _, err := store.Get(ctx, ref); !errors.Is(err, media.ErrMediaNotFound) {+ t.Fatalf("Get missing error = %v, want ErrMediaNotFound", err)+ }+}++func TestGet_RejectsCorruptPayloadAndWrongScope(t *testing.T) {+ backend := newFakeStore()+ store := New(backend, "task-1")+ ctx := taskContext("task-1")+ ref, err := store.Put(ctx, "html", "image/png", []byte("hello"))+ if err != nil {+ t.Fatal(err)+ }+ for key := range backend.kv {+ backend.kv[key] = "HELLO"+ }+ if _, err := store.Get(ctx, ref); err == nil || !strings.Contains(err.Error(), "digest mismatch") {+ t.Fatalf("Get corrupt error = %v, want digest mismatch", err)+ }++ wrongScope := ref+ wrongScope.Scope = "task-2"+ if _, err := store.Get(ctx, wrongScope); err == nil || !strings.Contains(err.Error(), "scope") {+ t.Fatalf("Get wrong scope error = %v, want scope rejection", err)+ }+ if _, err := store.Get(taskContext("task-2"), ref); err == nil || !strings.Contains(err.Error(), "task") {+ t.Fatalf("Get wrong task context error = %v, want task rejection", err)+ }+}++func TestGet_PropagatesBackendFailure(t *testing.T) {+ backend := newFakeStore()+ store := New(backend, "task-1")+ wantErr := errors.New("kvrocks unavailable")+ backend.getErr = wantErr+ ref := entity.MediaRef{+ Format: "html",+ Kind: entity.MediaKindKV,+ Scope: "task-1",+ SHA256: strings.Repeat("a", 64),+ MIME: "image/png",+ Size: 5,+ }+ if _, err := store.Get(taskContext("task-1"), ref); !errors.Is(err, wantErr) {+ t.Fatalf("Get error = %v, want %v", err, wantErr)+ }+}++func TestPut_FailsRatherThanSkippingCache(t *testing.T) {+ t.Run("write", func(t *testing.T) {+ backend := newFakeStore()+ backend.failSet = true+ if _, err := New(backend, "task-1").Put(taskContext("task-1"), "html", "image/png", []byte("hello")); err == nil {+ t.Fatal("Put succeeded when the backend rejected the write")+ }+ })+ t.Run("manifest", func(t *testing.T) {+ backend := newFakeStore()+ backend.expireFails = true+ if _, err := New(backend, "task-1").Put(taskContext("task-1"), "html", "image/png", []byte("hello")); err == nil {+ t.Fatal("Put succeeded when the manifest could not be bounded by TTL")+ }+ if len(backend.kv) != 0 {+ t.Fatalf("untracked media entries = %v, want rollback", backend.kv)+ }+ })+}++func TestPut_RejectsMissingStoreScopeAndOversizedImage(t *testing.T) {+ backend := newFakeStore()+ ctx := taskContext("task-1")+ if _, err := New(backend, "").Put(ctx, "html", "image/png", []byte("hello")); err == nil {+ t.Fatal("Put accepted an empty scope")+ }+ if _, err := New(nil, "task-1").Put(ctx, "html", "image/png", []byte("hello")); err == nil {+ t.Fatal("Put accepted an unavailable cache")+ }+ t.Setenv("RAGFLOW_HTML_IMAGE_MAX_BYTES", "5")+ data := make([]byte, 6)+ if _, err := New(backend, "task-1").Put(ctx, "html", "image/png", data); err == nil {+ t.Fatal("Put accepted an oversized image")+ }+}++func TestPurgeTask_RemovesMediaEntriesThroughMediaManifest(t *testing.T) {+ backend := newFakeStore()+ store := New(backend, "task-1")+ ctx := taskContext("task-1")+ if _, err := store.Put(ctx, "html", "image/png", []byte("hello")); err != nil {+ t.Fatal(err)+ }+ if err := PurgeTask(ctx, backend, "task-1"); err != nil {+ t.Fatal(err)+ }+ if len(backend.kv) != 0 {+ t.Fatalf("cache after purge = %v, want empty", backend.kv)+ }+ if len(backend.sets) != 0 {+ t.Fatalf("manifest after purge = %v, want empty", backend.sets)+ }+}++func TestTTLIsOneDay(t *testing.T) {+ if TTL != 24*time.Hour {+ t.Fatalf("TTL = %v, want 24h", TTL)+ }+}++func TestMediaManifestDoesNotTouchChunkManifest(t *testing.T) {+ backend := newFakeStore()+ ctx := taskContext("task-1")+ backend.SAdd(ctx, "kc:manifest:task-1", "kc:model-result")+ backend.Set(ctx, "kc:model-result", "result", 7*24*time.Hour)+ if _, err := New(backend, "task-1").Put(ctx, "html", "image/png", []byte("hello")); err != nil {+ t.Fatal(err)+ }+ if backend.ttl[manifestKey("task-1")] != TTL {+ t.Fatal("media manifest must expire in one day")+ }+ if err := PurgeTask(ctx, backend, "task-1"); err != nil {+ t.Fatal(err)+ }+ if backend.kv["kc:model-result"] != "result" || !backend.sets["kc:manifest:task-1"]["kc:model-result"] {+ t.Fatal("media cleanup modified chunk cache")+ }+}++func TestPutAllowsMoreThan256DistinctImages(t *testing.T) {+ backend := newFakeStore()+ store := New(backend, "task-1")+ ctx := taskContext("task-1")+ for i := 0; i < 257; i++ {+ if _, err := store.Put(ctx, "html", "image/png", []byte(fmt.Sprintf("image-%d", i))); err != nil {+ t.Fatalf("image %d: %v", i, err)+ }+ }+}++func TestPurgeTaskRetriesAfterPartialDeleteFailure(t *testing.T) {+ backend := newFakeStore()+ ctx := taskContext("task-1")+ store := New(backend, "task-1")+ ref, err := store.Put(ctx, "html", "image/png", []byte("first"))+ if err != nil {+ t.Fatal(err)+ }+ if _, err := store.Put(ctx, "html", "image/png", []byte("second")); err != nil {+ t.Fatal(err)+ }+ key := store.key(ref.SHA256)+ backend.deleteFails = map[string]bool{key: true}+ if err := PurgeTask(ctx, backend, "task-1"); err == nil {+ t.Fatal("expected delete failure")+ }+ if len(backend.sets[manifestKey("task-1")]) != 2 {+ t.Fatal("manifest lost after failed purge")+ }+ delete(backend.deleteFails, key)+ if err := PurgeTask(ctx, backend, "task-1"); err != nil {+ t.Fatal(err)+ }+ if len(backend.kv) != 0 || len(backend.sets) != 0 {+ t.Fatal("retry did not clear media")+ }+}++func TestRetryRepopulatesMediaAfterCacheMiss(t *testing.T) {+ backend := newFakeStore()+ ctx := taskContext("task-1")+ ref, err := New(backend, "task-1").Put(ctx, "html", "image/png", []byte("hello"))+ if err != nil {+ t.Fatal(err)+ }+ for key := range backend.kv {+ delete(backend.kv, key)+ }+ if _, err := New(backend, "task-1").Get(ctx, ref); !errors.Is(err, media.ErrMediaNotFound) {+ t.Fatalf("miss = %v", err)+ }+ retry := New(backend, "task-1")+ retryRef, err := retry.Put(ctx, "html", "image/png", []byte("hello"))+ if err != nil {+ t.Fatal(err)+ }+ got, err := retry.Get(ctx, retryRef)+ if err != nil || string(got) != "hello" {+ t.Fatalf("retry read = %q, %v", got, err)+ }+}++func TestPutRestoresMissingMediaInSameStore(t *testing.T) {+ backend := newFakeStore()+ ctx := taskContext("task-1")+ store := New(backend, "task-1")+ data := []byte("hello")+ ref, err := store.Put(ctx, "html", "image/png", data)+ if err != nil {+ t.Fatal(err)+ }+ backend.Delete(ctx, store.key(ref.SHA256))+ backend.Delete(ctx, manifestKey("task-1"))++ restored, err := store.Put(ctx, "html", "image/png", data)+ if err != nil {+ t.Fatal(err)+ }+ got, err := store.Get(ctx, restored)+ if err != nil || string(got) != string(data) {+ t.Fatalf("restored media = %q, %v", got, err)+ }+ if err := PurgeTask(ctx, backend, "task-1"); err != nil {+ t.Fatal(err)+ }+ if len(backend.kv) != 0 || len(backend.sets) != 0 {+ t.Fatal("restored media was not purged")+ }+}++func TestPutDuplicateRefreshesTTLAndReportsWriteFailure(t *testing.T) {+ backend := newFakeStore()+ ctx := taskContext("task-1")+ store := New(backend, "task-1")+ data := []byte("hello")+ ref, err := store.Put(ctx, "html", "image/png", data)+ if err != nil {+ t.Fatal(err)+ }+ key := store.key(ref.SHA256)+ backend.ttl[key] = time.Second+ backend.ttl[manifestKey("task-1")] = time.Second+ if _, err := store.Put(ctx, "html", "image/png", data); err != nil {+ t.Fatal(err)+ }+ if backend.ttl[key] != TTL || backend.ttl[manifestKey("task-1")] != TTL {+ t.Fatal("duplicate put did not refresh media and manifest TTLs")+ }+ backend.failSet = true+ if _, err := store.Put(ctx, "html", "image/png", data); err == nil {+ t.Fatal("duplicate put succeeded when the backend rejected the write")+ }+}diff --git a/internal/ingestion/pipeline/cleanup.go b/internal/ingestion/pipeline/cleanup.goindex 40d5541ffa..0bb0b5b974 100644--- a/internal/ingestion/pipeline/cleanup.go+++ b/internal/ingestion/pipeline/cleanup.go@@ -5,15 +5,14 @@ import ("errors""ragflow/internal/ingestion/chunkcache"+ "ragflow/internal/ingestion/mediacache")-// PurgeTaskState removes the per-chunk cache state for a task using the-// process-wide Kvrocks client. The checkpoint (eino resume) store was removed-// from the ingestion pipeline, so only the per-chunk LLM/embedding results are-// purged here; a rerun therefore starts with a cold chunk cache.+// PurgeTaskState removes the run-scoped cache state for a task using the+// process-wide Kvrocks client. Model results and media use separate manifests.func PurgeTaskState(ctx context.Context, taskID string) error {if taskID == "" {return errors.New("task state cleanup requires a task id")}- return chunkcache.PurgeTask(ctx, chunkcache.Client(), taskID)+ return errors.Join(chunkcache.PurgeTask(ctx, chunkcache.Client(), taskID), mediacache.PurgeTask(ctx, chunkcache.Client(), taskID))}diff --git a/internal/ingestion/pipeline/html_media_real_integration_test.go b/internal/ingestion/pipeline/html_media_real_integration_test.gonew file mode 100644index 0000000000..44dc6f64a8--- /dev/null+++ b/internal/ingestion/pipeline/html_media_real_integration_test.go@@ -0,0 +1,243 @@+//go:build integration++package pipeline++import (+ "bytes"+ "context"+ "encoding/base64"+ "errors"+ "fmt"+ "os"+ "path/filepath"+ "testing"+ "time"++ "github.com/cespare/xxhash/v2"+ "gopkg.in/yaml.v3"+ "ragflow/internal/common"+ "ragflow/internal/dao"+ "ragflow/internal/engine/kvrocks"+ "ragflow/internal/entity"+ component "ragflow/internal/ingestion/component"+ "ragflow/internal/ingestion/component/schema"+ "ragflow/internal/ingestion/mediacache"+ "ragflow/internal/parser/media"+ "ragflow/internal/parser/parser"+ "ragflow/internal/server"+ "ragflow/internal/server/config"+ "ragflow/internal/storage"+ "ragflow/internal/tokenizer"+)++// TestHTMLMediaRealServices exercises the normal ingestion canvas using real+// MySQL, Kvrocks and MinIO. The source HTML contains a one-pixel PNG.+func TestHTMLMediaRealServices(t *testing.T) {+ if os.Getenv("RAGFLOW_REAL_HTML_MEDIA_TEST") != "1" {+ t.Skip("set RAGFLOW_REAL_HTML_MEDIA_TEST=1 with configured MySQL, Kvrocks and MinIO")+ }+ if common.GetEnv(common.EnvRAGFlowDictPath) == "" {+ const dictPath = "/usr/share/infinity/resource"+ if _, err := os.Stat(filepath.Join(dictPath, "rag", "huqie.txt")); err != nil {+ t.Fatalf("tokenizer resource: %v", err)+ }+ t.Setenv(common.EnvRAGFlowDictPath, dictPath)+ }+ if err := tokenizer.Init(&tokenizer.PoolConfig{DictPath: "/usr/share/infinity/resource", MinSize: 1, MaxSize: 2, IdleTimeout: 30 * time.Second, AcquireTimeout: 5 * time.Second}); err != nil {+ t.Fatalf("tokenizer initialization: %v", err)+ }+ cfg := loadHTMLMediaIntegrationConfig(t)+ db := mustOpenRealMySQL(t, cfg)+ sqlDB, err := db.DB()+ if err != nil {+ t.Fatal(err)+ }+ sqlDB.SetMaxOpenConns(1)+ if err := db.Exec("SET SESSION sql_mode = ''").Error; err != nil {+ t.Fatal(err)+ }+ t.Cleanup(func() { _ = sqlDB.Close() })+ if err := db.AutoMigrate(&entity.Tenant{}, &entity.UserTenant{}, &entity.Knowledgebase{}, &entity.Document{}, &entity.File{}, &entity.File2Document{}); err != nil {+ t.Fatal(err)+ }+ if err := kvrocks.Init(t.Context()); err != nil {+ t.Fatal(err)+ }+ kv := kvrocks.Get()+ stg, err := storage.NewMinioStorage(cfg.GetMinioConfig())+ if err != nil {+ t.Fatal(err)+ }+ readyCtx, cancel := context.WithTimeout(t.Context(), 30*time.Second)+ defer cancel()+ for {+ _, err := stg.BucketExistsWithError(readyCtx, "ragflow-html-media-probe")+ if err == nil {+ break+ }+ select {+ case <-readyCtx.Done():+ t.Fatalf("MinIO S3 not ready: %v", err)+ case <-time.After(250 * time.Millisecond):+ }+ }+ originalDB := dao.DB+ originalStorage := storage.GetStorageFactory().GetStorage()+ originalResolver := component.ResolveDocumentStorageOverride+ dao.DB = db+ storage.GetStorageFactory().SetStorage(stg)+ component.ResolveDocumentStorageOverride = nil+ t.Cleanup(func() {+ dao.DB = originalDB+ storage.GetStorageFactory().SetStorage(originalStorage)+ component.ResolveDocumentStorageOverride = originalResolver+ })+ template, err := os.ReadFile(filepath.Join(repoRootFromPipelineTest(t), "internal/ingestion/pipeline/template/ingestion_pipeline_general.json"))+ if err != nil {+ t.Fatal(err)+ }+ template = disableTokenizerEmbeddingForTemplate(t, template)+ suffix := fmt.Sprintf("%d", time.Now().UnixNano())+ tenantID, kbID := limit32("it_tenant_"+suffix), s3SafeBucketName("it-kb-"+suffix)+ docID, fileID := limit32("it_doc_"+suffix), limit32("it_file_"+suffix)+ taskID := "it-html-" + suffix+ bucket := s3SafeBucketName(kbID)+ objectPath := "integration/" + taskID + "/image.html"+ const png64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="+ png, err := base64.StdEncoding.DecodeString(png64)+ if err != nil {+ t.Fatal(err)+ }+ html := `<p>HTML image fixture</p><img alt="sample figure" src="data:image/png;base64,` + png64 + `">`+ mustSeedRealPipelineDocument(t, db, stg, tenantID, kbID, docID, fileID, bucket, objectPath, "image.html", html)+ t.Cleanup(func() {+ _ = mediacache.PurgeTask(context.Background(), kv, taskID)+ cleanupRealPipelineDocument(db, stg, tenantID, kbID, docID, fileID, bucket, objectPath)+ })+ if err := db.Model(&entity.Document{}).Where("id = ?", docID).Updates(map[string]any{"type": "html", "suffix": ".html"}).Error; err != nil {+ t.Fatal(err)+ }+ if err := db.Model(&entity.File{}).Where("id = ?", fileID).Update("type", "html").Error; err != nil {+ t.Fatal(err)+ }+ pipe, err := NewPipelineFromDSL(template, taskID, WithDocumentID(docID), WithKV(kv))+ if err != nil {+ t.Fatal(err)+ }+ out, err := pipe.Run(t.Context(), map[string]any{"doc_id": docID, "kb_id": kbID, "tenant_id": tenantID}, nil)+ if err != nil {+ t.Fatal(err)+ }+ state := stateFromRunOutput(t, out)+ docs, ok := state["Parser:HipSignsRhyme"]["json"].([]parser.DocItem)+ if !ok {+ t.Fatalf("parser output = %T", state["Parser:HipSignsRhyme"]["json"])+ }+ var ref *entity.MediaRef+ for _, item := range docs {+ m := item.ToMap()+ if m["media_ref"] != nil {+ ref = entity.MediaRefFromAny(m["media_ref"])+ if m["image"] != nil {+ t.Fatal("parser retained inline image")+ }+ }+ }+ if ref == nil {+ t.Fatal("parser did not emit media_ref")+ }+ cached, err := mediacache.New(kv, taskID).Get(t.Context(), *ref)+ if err != nil || !bytes.Equal(cached, png) {+ t.Fatalf("cached bytes differ: %v", err)+ }+ chunks, ok := schema.ChunkCarrierToMaps(state["GeneralChunker:SixApplesFall"]["chunks"])+ if !ok {+ t.Fatal("missing chunker output")+ }+ foundImage := false+ for _, ck := range chunks {+ id, _ := ck["id"].(string)+ imgID, _ := ck["img_id"].(string)+ if imgID == "" {+ continue+ }+ if imgID != kbID+"-"+id || ck["media_ref"] != nil {+ t.Fatalf("invalid image chunk: %v", ck)+ }+ got, err := stg.Get(t.Context(), kbID, id)+ if err != nil {+ t.Fatal(err)+ }+ t.Cleanup(func() { _ = stg.Remove(context.Background(), kbID, id) })+ if !bytes.Equal(got, png) {+ t.Fatal("stored image does not match source")+ }+ foundImage = true+ }+ if !foundImage {+ t.Fatalf("chunker produced no uploaded image: chunks=%#v state=%#v", chunks, state["GeneralChunker:SixApplesFall"])+ }+ key := fmt.Sprintf("mc:media:%x:%s", xxhash.Sum64String(taskID), ref.SHA256)+ ttl, err := kv.GetClient().TTL(t.Context(), key).Result()+ if err != nil || ttl <= 23*time.Hour || ttl > mediacache.TTL {+ t.Fatalf("media TTL = %v, %v", ttl, err)+ }+ if err := kv.GetClient().Expire(t.Context(), key, time.Millisecond).Err(); err != nil {+ t.Fatal(err)+ }+ deadline := time.Now().Add(2 * time.Second)+ for {+ _, err = mediacache.New(kv, taskID).Get(t.Context(), *ref)+ if errors.Is(err, media.ErrMediaNotFound) {+ break+ }+ if err != nil || time.Now().After(deadline) {+ t.Fatalf("media did not expire: %v", err)+ }+ time.Sleep(10 * time.Millisecond)+ }+ retry := mediacache.New(kv, taskID)+ retryRef, err := retry.Put(t.Context(), "html", "image/png", png)+ if err != nil {+ t.Fatal(err)+ }+ if got, err := retry.Get(t.Context(), retryRef); err != nil || !bytes.Equal(got, png) {+ t.Fatalf("retry cache bytes: %v", err)+ }+ if err := mediacache.PurgeTask(t.Context(), kv, taskID); err != nil {+ t.Fatal(err)+ }+ if _, err := retry.Get(t.Context(), retryRef); !errors.Is(err, media.ErrMediaNotFound) {+ t.Fatalf("purged cache read: %v", err)+ }+}++// loadHTMLMediaIntegrationConfig uses the CI service addresses when set.+func loadHTMLMediaIntegrationConfig(t *testing.T) *config.Config {+ t.Helper()+ kvAddr := os.Getenv("RAGFLOW_TEST_KVROCKS_ADDR")+ if kvAddr == "" {+ return mustLoadRealIntegrationConfig(t)+ }+ cfg := map[string]any{+ "general": map[string]any{"cache_engine": "kvrocks"},+ "mysql": map[string]any{"host": os.Getenv("RAGFLOW_MYSQL_HOST"), "port": os.Getenv("RAGFLOW_MYSQL_PORT"), "password": os.Getenv("MYSQL_PASSWORD")},+ "minio": map[string]any{"host": os.Getenv("RAGFLOW_MINIO_HOST"), "user": os.Getenv("MINIO_USER"), "password": os.Getenv("MINIO_PASSWORD")},+ "kvrocks": map[string]any{"host": kvAddr, "password": os.Getenv("REDIS_PASSWORD"), "db": 1},+ }+ data, err := yaml.Marshal(cfg)+ if err != nil {+ t.Fatal(err)+ }+ path := filepath.Join(t.TempDir(), "service_conf.yaml")+ if err := os.WriteFile(path, data, 0600); err != nil {+ t.Fatal(err)+ }+ if err := common.InitLogger("info", common.FileOutput{}, ""); err != nil {+ t.Fatal(err)+ }+ if err := server.Init(path); err != nil {+ t.Fatal(err)+ }+ return server.GetConfig()+}diff --git a/internal/ingestion/pipeline/pipeline.go b/internal/ingestion/pipeline/pipeline.goindex 70a37ac9c3..d227476282 100644--- a/internal/ingestion/pipeline/pipeline.go+++ b/internal/ingestion/pipeline/pipeline.go@@ -30,6 +30,8 @@ import (kvrocks "ragflow/internal/engine/kvrocks""ragflow/internal/ingestion/component/globals""ragflow/internal/ingestion/component/schema"+ "ragflow/internal/ingestion/mediacache"+ "ragflow/internal/parser/media""ragflow/internal/utility""go.uber.org/zap"@@ -43,6 +45,7 @@ type Pipeline struct {canvas *canvas.Canvastracker *canvas.RunTracker // optional injected; nil -> resolve at Runkv *kvrocks.Client // optional; nil -> no tracker fallback (unit/test runs)+ media media.Cache // optional injected run media cachefactory runtime.ComponentFactory // optional instance-scoped component factorysink ProgressSink // optional progress sink; nil -> drop events (DB-independent)}@@ -186,8 +189,7 @@ func cloneMapOrEmpty(m map[string]any) map[string]any {}// defaultTrackerTTL is the expiry applied to the RunTracker run-status hash.-// It matches the per-chunk cache TTL (chunkcache.TTL) so both expire on the-// same horizon.+// It matches the model-result cache TTL; media has its own one-day TTL.var defaultTrackerTTL = 7 * 24 * time.Hour// Run executes the full ingestion graph described by the canonical DSL.@@ -217,7 +219,7 @@ func (p *Pipeline) Run(ctx context.Context, inputs map[string]any, overrideParam// MarkSucceeded/MarkFailed/MarkCancelled marks). Resume-from-checkpoint is// intentionally not supported: the pipeline always runs the full graph// from the entry node, and component-level replay decisions (e.g. serving- // prior LLM/embedding results from the per-chunk cache) belong to the+ // prior LLM/embedding results from the run cache) belong to the// components themselves.tracker := p.resolveTracker()@@ -262,10 +264,21 @@ func (p *Pipeline) Run(ctx context.Context, inputs map[string]any, overrideParam// them mid-run.globals.SeedIngestionGlobals(runCtx, current)// Expose the task id on the run context so every component can register the- // per-chunk cache keys it writes into the task manifest (chunkcache). Without+ // run-cache keys it writes into the task manifest (chunkcache). Without// this the manifest is never populated and PurgeTask on success becomes a// no-op, leaving orphaned cache entries until TTL expiry.globals.SetTaskID(runCtx, p.taskID)+ mediaCache := p.media+ if mediaCache == nil && p.kv != nil {+ scope := p.taskID+ if scope == "" {+ scope = p.documentID+ }+ mediaCache = mediacache.New(p.kv, scope)+ }+ if mediaCache != nil {+ runCtx = media.WithCache(runCtx, mediaCache)+ }return p.runPlain(runCtx, current, compiled, tracker, runState)}diff --git a/internal/ingestion/pipeline/pipeline_test.go b/internal/ingestion/pipeline/pipeline_test.goindex e5970a21bc..0ed1d0912d 100644--- a/internal/ingestion/pipeline/pipeline_test.go+++ b/internal/ingestion/pipeline/pipeline_test.go@@ -27,6 +27,9 @@ import ("ragflow/internal/agent/canvas""ragflow/internal/agent/runtime"+ "ragflow/internal/entity"+ "ragflow/internal/ingestion/component/globals"+ "ragflow/internal/parser/media""github.com/alicebob/miniredis/v2""github.com/redis/go-redis/v9"@@ -39,6 +42,31 @@ type mockCanvasStage struct {calls int}+type pipelineContextMediaCache struct {+ scope string+}++func (c *pipelineContextMediaCache) Put(context.Context, string, string, []byte) (entity.MediaRef, error) {+ return entity.MediaRef{Scope: c.scope}, nil+}++func (c *pipelineContextMediaCache) Get(context.Context, entity.MediaRef) ([]byte, error) {+ return nil, nil+}++type mediaCacheContextStage struct{}++func (*mediaCacheContextStage) Invoke(ctx context.Context, _ *gorm.DB, _ map[string]any) (map[string]any, error) {+ cache, ok := media.CacheFromContext(ctx).(*pipelineContextMediaCache)+ if !ok {+ return nil, errors.New("pipeline media cache is not attached")+ }+ if got := globals.TaskID(ctx); got != cache.scope {+ return nil, fmt.Errorf("pipeline task id = %q, want media cache scope %q", got, cache.scope)+ }+ return map[string]any{"media_cache_scope": cache.scope}, nil+}+func (m *mockCanvasStage) Invoke(_ context.Context, _ *gorm.DB, inputs map[string]any) (map[string]any, error) {m.called = truem.calls++@@ -204,6 +232,44 @@ func TestPipelineRun_InstanceFactoryOverridesDefaultFactory(t *testing.T) {}}+func TestPipelineRunAttachesInjectedMediaCacheWithTaskScope(t *testing.T) {+ const stageName = "p.MediaCacheContextStage"+ runtime.MustRegister(stageName, runtime.CategoryIngestion,+ func(_ string, _ map[string]any) (runtime.Component, error) {+ return &mediaCacheContextStage{}, nil+ },+ runtime.Metadata{Version: "1.0.0"})++ const taskID = "task-media-cache"+ cache := &pipelineContextMediaCache{scope: taskID}+ pipe, err := NewPipelineFromDSL([]byte(`{+ "dsl": {+ "components": {+ "begin": {"obj": {"component_name": "Begin", "params": {}}, "downstream": ["stage"]},+ "stage": {"obj": {"component_name": "p.MediaCacheContextStage", "params": {}}, "upstream": ["begin"]}+ },+ "path": ["begin", "stage"],+ "graph": {"nodes": []}+ }+ }`), taskID, WithDocumentID("doc-media-cache"))+ if err != nil {+ t.Fatalf("NewPipelineFromDSL: %v", err)+ }+ pipe.media = cache++ out, err := pipe.Run(t.Context(), map[string]any{"name": "image.html"}, nil)+ if err != nil {+ t.Fatalf("Run: %v", err)+ }+ stage, ok := out["stage"].(map[string]any)+ if !ok {+ t.Fatalf("stage output = %T, want map[string]any", out["stage"])+ }+ if got := stage["media_cache_scope"]; got != taskID {+ t.Fatalf("media cache scope = %v, want %q", got, taskID)+ }+}+func TestPipelineRun_TaskScopedFactoriesDoNotLeakAcrossConcurrentPipelines(t *testing.T) {origFactory := runtime.DefaultFactory()runtime.SetDefaultFactory(func(_ string, _ map[string]any) (runtime.Component, error) {diff --git a/internal/ingestion/task/indexdoc/process.go b/internal/ingestion/task/indexdoc/process.goindex 4dfd2d5055..2728bee4ed 100644--- a/internal/ingestion/task/indexdoc/process.go+++ b/internal/ingestion/task/indexdoc/process.go@@ -168,9 +168,11 @@ func cleanupConsumedChunkFields(ck map[string]any) {// The Python index doc carries none of them — its chunk builder emits only the// persist fields — but Go's chunker hands them on, and the write boundary is// where they stop: Elasticsearch and Vastbase would add a field for each key,-// and Infinity would drop each key at insert with a warning.+// and Infinity would drop each key at insert with a warning. media_ref is the+// deferred-image reference consumed by the upload pass; a chunk that still+// carries one must not reach the index.var pipelineOnlyFields = []string{- "tk_nums", "layout", "layout_type", "layoutno", "image",+ "tk_nums", "layout", "layout_type", "layoutno", "image", "media_ref","context_above", "context_below", "page_number", "_preserve_order","table_id", "sheet", "sheet_index", "headers", "cells","row_start", "row_end", "col_start", "col_end",diff --git a/internal/ingestion/task/indexdoc/process_test.go b/internal/ingestion/task/indexdoc/process_test.goindex 8059cd138e..e0cfb075b6 100644--- a/internal/ingestion/task/indexdoc/process_test.go+++ b/internal/ingestion/task/indexdoc/process_test.go@@ -698,6 +698,7 @@ func TestProcessChunksForPipeline_StripsPipelineOnlyFields(t *testing.T) {// Every bookkeeping key the chunkers/parsers can leave on a chunk."tk_nums": 3, "layout": "text", "layout_type": "text","layoutno": "0", "image": "data:image/png;base64,AAAA",+ "media_ref": map[string]any{"format": "html"},"context_above": "above", "context_below": "below", "page_number": 2,"table_id": "t1", "sheet": "s1", "sheet_index": 0,"headers": []string{"h"}, "cells": []string{"c"},diff --git a/internal/ingestion/task/pipeline_executor.go b/internal/ingestion/task/pipeline_executor.goindex 727de8f315..dde2b6fb61 100644--- a/internal/ingestion/task/pipeline_executor.go+++ b/internal/ingestion/task/pipeline_executor.go@@ -36,9 +36,11 @@ import ("ragflow/internal/ingestion/component/globals"kccommon "ragflow/internal/ingestion/component/knowledge_compiler/common""ragflow/internal/ingestion/knowledge_compile"+ "ragflow/internal/ingestion/mediacache"pipelinepkg "ragflow/internal/ingestion/pipeline"indexdoc "ragflow/internal/ingestion/task/indexdoc"+ "go.uber.org/zap""gorm.io/gorm")@@ -374,14 +376,17 @@ func (s *PipelineExecutor) processOutput(ctx context.Context, pipelineOutput map// Persist is now fully durable: every failure-capable step above// (index write, compiled-product reconcile, Wiki active-MAP state) has- // succeeded. Only now drop the per-chunk cache entries this task produced,- // so a failure in any of those steps leaves the cache intact for the retry —- // the retry resumes after the Parser checkpoint and would otherwise have to- // re-pay every embedding/LLM call, which is exactly the cost this cache- // exists to absorb. PurgeTask is best-effort and silent when no manifest- // exists (e.g. a Redis-less run, where chunkcache.Client() is nil).+ // succeeded. Only now drop the run-scoped cache entries this task produced,+ // so a failure in any of those steps leaves chunk results and parser media+ // intact for retry. Cleanup is best-effort; failed media cleanup is logged+ // and the entries expire independently.if s.taskCtx.IngestionTask != nil && s.taskCtx.IngestionTask.ID != "" {chunkcache.PurgeTask(ctx, chunkcache.Client(), s.taskCtx.IngestionTask.ID)+ if s.deps.KV != nil {+ if err := mediacache.PurgeTask(ctx, s.deps.KV, s.taskCtx.IngestionTask.ID); err != nil {+ common.Warn("failed to purge task media cache", zap.String("task_id", s.taskCtx.IngestionTask.ID), zap.Error(err))+ }+ }}return &PipelineResult{diff --git a/internal/parser/parser/charset.go b/internal/parser/charset/charset.gosimilarity index 97%rename from internal/parser/parser/charset.gorename to internal/parser/charset/charset.goindex 6db1208a92..e2a2562805 100644--- a/internal/parser/parser/charset.go+++ b/internal/parser/charset/charset.go@@ -14,7 +14,7 @@// limitations under the License.//-package parser+package charset// Shared charset-label resolution and decode-acceptance helpers. Both// email_parser.go (RFC 2047 headers, mail bodies) and html_parser.go@@ -49,7 +49,7 @@ func canonicalCharsetLabel(label string) string {return strings.NewReplacer("-", "", "_", "").Replace(strings.ToLower(strings.TrimSpace(label)))}-// charsetEncoding maps a charset label to its decoder, covering the+// CharsetEncoding maps a charset label to its decoder, covering the// charsets common in real-world mail and legacy HTML beyond utf-8: the// Chinese families (gb2312/gbk/gb18030, big5), shift_jis, euc-kr, and// latin-1. It is the single label resolver shared by the RFC 2047 header@@ -59,7 +59,7 @@ func canonicalCharsetLabel(label string) string {// The "gb2312" label maps to GBK, not HZGB2312: mail labeled gb2312 carries// plain 8-bit GB2312 bytes, while HZGB2312 only decodes the 7-bit HZ escape// form used under the distinct "hz-gb-2312" label.-func charsetEncoding(charset string) (encoding.Encoding, bool) {+func CharsetEncoding(charset string) (encoding.Encoding, bool) {switch canonicalCharsetLabel(charset) {case "gb2312", "gbk":return simplifiedchinese.GBK, true@@ -91,7 +91,7 @@ func decodeWithCharset(payload []byte, charset string) (string, error) {}return "", fmt.Errorf("invalid utf-8")}- if enc, ok := charsetEncoding(charset); ok {+ if enc, ok := CharsetEncoding(charset); ok {return decodeTransform(payload, enc.NewDecoder())}if enc, _ := htmlcharset.Lookup(charset); enc != nil {@@ -101,13 +101,13 @@ func decodeWithCharset(payload []byte, charset string) (string, error) {}// isRecognizedCharset reports whether charset maps to a known decoder-// either via our shared charsetEncoding resolver or htmlcharset.Lookup.+// either via our shared CharsetEncoding resolver or htmlcharset.Lookup.func isRecognizedCharset(charset string) bool {switch canonicalCharsetLabel(charset) {case "utf8", "":return true}- if _, ok := charsetEncoding(charset); ok {+ if _, ok := CharsetEncoding(charset); ok {return true}if enc, _ := htmlcharset.Lookup(charset); enc != nil {diff --git a/internal/parser/parser/charset_test.go b/internal/parser/charset/charset_test.gosimilarity index 70%rename from internal/parser/parser/charset_test.gorename to internal/parser/charset/charset_test.goindex 23c1c0988b..9c2227d6f9 100644--- a/internal/parser/parser/charset_test.go+++ b/internal/parser/charset/charset_test.go@@ -1,9 +1,6 @@-package parser+package charsetimport (- "archive/zip"- "bytes"- "context""strings""testing""unicode/utf8"@@ -16,7 +13,7 @@ import ()// TestCharsetEncodingSharedLabelContract locks the single-label contract of-// charsetEncoding: every fallback label the HTML parser may walk (and the+// CharsetEncoding: every fallback label the HTML parser may walk (and the// mail chain ships) resolves through the shared resolver, detector/WHATWG// spellings fold onto the same encoder, and labels outside the shared// family (e.g. windows-1252, handled by the HTML prescan layer, or utf-8,@@ -25,8 +22,8 @@ import (func TestCharsetEncodingSharedLabelContract(t *testing.T) {mailLabels := []string{"gb2312", "gbk", "gb18030", "hz-gb-2312", "big5", "shift_jis", "sjis", "euc-kr", "iso-8859-1", "latin1"}for _, label := range append(mailLabels, fallbackCharsetLabels...) {- if _, ok := charsetEncoding(label); !ok {- t.Errorf("charsetEncoding(%q) = (_, false); the shared resolver must cover every mail-chain and HTML-fallback label", label)+ if _, ok := CharsetEncoding(label); !ok {+ t.Errorf("CharsetEncoding(%q) = (_, false); the shared resolver must cover every mail-chain and HTML-fallback label", label)}}@@ -42,16 +39,16 @@ func TestCharsetEncodingSharedLabelContract(t *testing.T) {" Big5 ": "big5",}for alias, label := range aliases {- aliasEnc, aliasOK := charsetEncoding(alias)- labelEnc, labelOK := charsetEncoding(label)+ aliasEnc, aliasOK := CharsetEncoding(alias)+ labelEnc, labelOK := CharsetEncoding(label)if !aliasOK || !labelOK || aliasEnc != labelEnc {- t.Errorf("charsetEncoding(%q) = (%v, %v), charsetEncoding(%q) = (%v, %v); alias spelling must fold onto the same encoder", alias, aliasEnc, aliasOK, label, labelEnc, labelOK)+ t.Errorf("CharsetEncoding(%q) = (%v, %v), CharsetEncoding(%q) = (%v, %v); alias spelling must fold onto the same encoder", alias, aliasEnc, aliasOK, label, labelEnc, labelOK)}}for _, label := range []string{"windows-1252", "utf-8", "utf-16", "euc-jp", ""} {- if _, ok := charsetEncoding(label); ok {- t.Errorf("charsetEncoding(%q) = (_, true); labels handled elsewhere (prescan / native utf-8) must not enter the shared resolver", label)+ if _, ok := CharsetEncoding(label); ok {+ t.Errorf("CharsetEncoding(%q) = (_, true); labels handled elsewhere (prescan / native utf-8) must not enter the shared resolver", label)}}}@@ -150,87 +147,6 @@ func TestDecodeToUTF8(t *testing.T) {}}-func TestCSVParser_GBK(t *testing.T) {- csvText := "产品,分类,价格,备注\n笔记本电脑,电子,6999.00,\"特价销售,送鼠标\"\n无线耳机,配件,399.00,\"热销\"\n"- gbkBytes, err := simplifiedchinese.GBK.NewEncoder().Bytes([]byte(csvText))- if err != nil {- t.Fatalf("GBK encode: %v", err)- }-- p := NewCSVParser()- res := p.ParseWithResult(context.Background(), "products.csv", gbkBytes)- if res.Err != nil {- t.Fatalf("CSVParser.ParseWithResult failed: %v", res.Err)- }- if len(res.JSON) == 0 {- t.Fatalf("CSVParser returned no JSON items")- }- var rowText strings.Builder- for _, item := range ItemsToMaps(res.JSON) {- text := tableItemHTML(t, item)- rowText.WriteString(text)- }- if strings.ContainsRune(rowText.String(), '\ufffd') {- t.Errorf("CSV output contains replacement runes: %s", rowText.String())- }- for _, want := range []string{"笔记本电脑", "电子", "特价销售,送鼠标", "无线耳机"} {- if !strings.Contains(rowText.String(), want) {- t.Errorf("CSV output missing expected substring %q; got: %s", want, rowText.String())- }- }- if enc, _ := res.File["encoding"].(string); enc != "gb18030" && enc != "gbk" && enc != "gb2312" {- t.Errorf("CSV File.encoding = %q, want gbk/gb2312/gb18030", enc)- }-}--func TestEPUBParser_GB2312(t *testing.T) {- // Create an in-memory EPUB zip with GB2312-encoded chapter XHTML- chapterContent := `<?xml version="1.0" encoding="GB2312"?>-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">-<html xmlns="http://www.w3.org/1999/xhtml">-<head><title>第一章</title></head>-<body><h1>第一章 破晓</h1><p>这是一段包含中文的EPUB正文内容。</p></body>-</html>`- chapterGBK, err := simplifiedchinese.GBK.NewEncoder().Bytes([]byte(chapterContent))- if err != nil {- t.Fatalf("GBK encode: %v", err)- }-- containerXML := `<?xml version="1.0"?><container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container"><rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles></container>`- contentOPF := `<?xml version="1.0" encoding="utf-8"?><package xmlns="http://www.idpf.org/2007/opf" unique-identifier="BookID" version="2.0"><metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:title>测试</dc:title></metadata><manifest><item id="c1" href="c1.xhtml" media-type="application/xhtml+xml"/></manifest><spine><itemref idref="c1"/></spine></package>`-- buf := new(bytes.Buffer)- zw := zip.NewWriter(buf)- w, _ := zw.Create("META-INF/container.xml")- w.Write([]byte(containerXML))- w, _ = zw.Create("OEBPS/content.opf")- w.Write([]byte(contentOPF))- w, _ = zw.Create("OEBPS/c1.xhtml")- w.Write(chapterGBK)- zw.Close()-- p := NewEPUBParser()- res := p.ParseWithResult(context.Background(), "book.epub", buf.Bytes())- if res.Err != nil {- t.Fatalf("EPUBParser.ParseWithResult failed: %v", res.Err)- }- if len(res.JSON) == 0 {- t.Fatal("want non-empty JSON items from EPUB")- }- text := epubTestText(res)- if strings.ContainsRune(text, '\ufffd') {- t.Errorf("EPUB text contains replacement runes: %s", text)- }- for _, want := range []string{"第一章 破晓", "这是一段包含中文的EPUB正文内容。"} {- if !strings.Contains(text, want) {- t.Errorf("EPUB text missing %q; got: %s", want, text)- }- }- if enc, _ := res.File["encoding"].(string); enc != "gb2312" && enc != "gbk" && enc != "gb18030" {- t.Errorf("EPUB File.encoding = %q, want gb2312/gbk/gb18030", enc)- }-}-func TestDecodeToUTF8_HZGB2312Hint(t *testing.T) {// HZ-GB-2312 escape sequences (~{...~}) are pure 7-bit ASCII, hence valid UTF-8.// An explicit hint must decode via HZ-GB-2312 rather than returning bytes untouched.diff --git a/internal/parser/media/cache.go b/internal/parser/media/cache.gonew file mode 100644index 0000000000..8184920a45--- /dev/null+++ b/internal/parser/media/cache.go@@ -0,0 +1,75 @@+// 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.++package media++import (+ "context"+ "crypto/sha256"+ "encoding/hex"+ "errors"+ "fmt"++ "ragflow/internal/entity"+)++// ErrMediaNotFound reports that a valid reference has no cached payload.+// Cache transport, scope, size and digest failures use other errors and must+// be returned to the task rather than treated as a missing image.+var ErrMediaNotFound = errors.New("media: reference not found")++// Cache stores decoded image bytes for materialization by later ingestion+// components. Implementations own key scoping, lifecycle bookkeeping and+// validation of the payload size and digest before returning bytes from Get.+type Cache interface {+ Put(ctx context.Context, format, mime string, data []byte) (entity.MediaRef, error)+ Get(ctx context.Context, ref entity.MediaRef) ([]byte, error)+}++type cacheContextKey struct{}++// WithCache attaches the media cache used by parser-emitted references.+func WithCache(ctx context.Context, cache Cache) context.Context {+ return context.WithValue(ctx, cacheContextKey{}, cache)+}++// CacheFromContext returns the run-scoped media cache, or nil when the caller+// did not attach one. HTML images must fail rather than silently drop when it+// is absent.+func CacheFromContext(ctx context.Context) Cache {+ cache, _ := ctx.Value(cacheContextKey{}).(Cache)+ return cache+}++// ValidatePayload performs the shared cache integrity and size checks.+func ValidatePayload(data []byte, ref entity.MediaRef) ([]byte, error) {+ if len(data) > HTMLImageMaxBytes() {+ return nil, fmt.Errorf("media: image %s exceeds the %d-byte limit", shortMediaDigest(ref.SHA256), HTMLImageMaxBytes())+ }+ sum := sha256.Sum256(data)+ if got := hex.EncodeToString(sum[:]); got != ref.SHA256 {+ return nil, fmt.Errorf("media: image digest mismatch: reference %s, cache %s", shortMediaDigest(ref.SHA256), shortMediaDigest(got))+ }+ if ref.Size > 0 && int64(len(data)) != ref.Size {+ return nil, fmt.Errorf("media: image size mismatch: reference %d bytes, cache %d bytes", ref.Size, len(data))+ }+ return data, nil+}++func shortMediaDigest(digest string) string {+ if len(digest) <= 12 {+ return digest+ }+ return digest[:12]+}diff --git a/internal/parser/media/html.go b/internal/parser/media/html.gonew file mode 100644index 0000000000..6dbf3d3975--- /dev/null+++ b/internal/parser/media/html.go@@ -0,0 +1,123 @@+// 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.++package media++import (+ "crypto/sha256"+ "encoding/base64"+ "os"+ "strconv"+ "strings"+)++// DecodeHTMLImageSource validates and decodes one inline HTML image. The HTML+// parser calls this once, then writes the bytes to the run media cache; later+// ingestion components materialize only the emitted MediaRef.+func DecodeHTMLImageSource(src string) (string, []byte, bool) {+ prefix, payload, ok := splitHTMLImageSource(src)+ if !ok {+ return "", nil, false+ }+ data, ok := decodeBase64ImagePayload(payload, HTMLImageMaxBytes())+ if !ok {+ return "", nil, false+ }+ return DataURIMediaType(prefix), data, true+}++// HTMLImageMaxBytes is the per-image limit for HTML media.+func HTMLImageMaxBytes() int {+ const defaultLimit = 32 << 20+ if n, err := strconv.Atoi(os.Getenv("RAGFLOW_HTML_IMAGE_MAX_BYTES")); err == nil && n > 0 && n <= int(^uint(0)>>1)/4*3 {+ return n+ }+ return defaultLimit+}++// HTMLImageExceedsLimit identifies oversized, syntactically valid data URIs.+func HTMLImageExceedsLimit(src string) bool {+ _, payload, ok := splitHTMLImageSource(src)+ if !ok {+ return false+ }+ payload = strings.ReplaceAll(strings.ReplaceAll(payload, "\r", ""), "\n", "")+ n := len(payload)+ if n == 0 {+ return false+ }+ padding := 0+ for padding < n && payload[n-1-padding] == '=' {+ padding+++ }+ if padding > 2 {+ return false+ }+ if n%4 == 1 {+ return false+ }+ decoded := base64.StdEncoding.DecodedLen((n+3)/4*4) - padding+ if n%4 != 0 {+ decoded -= 4 - n%4+ }+ return decoded > HTMLImageMaxBytes()+}++// splitHTMLImageSource validates the data-URI header and returns the normalized+// prefix and base64 payload.+func splitHTMLImageSource(src string) (prefix, payload string, ok bool) {+ src = strings.TrimSpace(src)+ if !IsHTMLDataImageSource(src) {+ return "", "", false+ }+ separator := strings.IndexByte(src, ',')+ if separator <= len("data:image/") || separator > 128 || !strings.EqualFold(src[separator-len(";base64"):separator], ";base64") {+ return "", "", false+ }+ return strings.ToLower(src[:separator+1]), src[separator+1:], true+}++// NormalizeHTMLImageSource validates an inline image while avoiding a decoded+// byte buffer. It remains the path for HTML layouts that intentionally keep+// the normalized data URI inline rather than storing it in the run cache.+func NormalizeHTMLImageSource(src string) (string, int64, [sha256.Size]byte, bool) {+ var sum [sha256.Size]byte+ prefix, payload, ok := splitHTMLImageSource(src)+ if !ok {+ return "", 0, sum, false+ }+ normalized, size, sum, ok := NormalizeBase64ImagePayload(payload, MaxImagePayloadBytes)+ if !ok {+ return "", 0, sum, false+ }+ return prefix + normalized, size, sum, true+}++// DataURIMediaType returns the media type of a normalized+// "data:<mime>;base64," URI.+func DataURIMediaType(uri string) string {+ colon := strings.IndexByte(uri, ':')+ semi := strings.IndexByte(uri, ';')+ if colon < 0 || semi <= colon+1 {+ return ""+ }+ return strings.ToLower(uri[colon+1 : semi])+}++// IsHTMLDataImageSource reports whether src is an image data URI.+func IsHTMLDataImageSource(src string) bool {+ const dataPrefix = "data:image/"+ src = strings.TrimSpace(src)+ return len(src) >= len(dataPrefix) && strings.EqualFold(src[:len(dataPrefix)], dataPrefix)+}diff --git a/internal/parser/media/html_test.go b/internal/parser/media/html_test.gonew file mode 100644index 0000000000..c07907a56a--- /dev/null+++ b/internal/parser/media/html_test.go@@ -0,0 +1,96 @@+// 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.++package media++import (+ "crypto/sha256"+ "strings"+ "testing"+)++func TestDecodeHTMLImageSourceCaseAndPadding(t *testing.T) {+ mime, data, ok := DecodeHTMLImageSource("DATA:IMAGE/PNG;BASE64,aGVsbG8")+ if !ok {+ t.Fatal("DecodeHTMLImageSource rejected a valid case-insensitive data URI")+ }+ if mime != "image/png" {+ t.Errorf("mime = %q, want image/png", mime)+ }+ if string(data) != "hello" {+ t.Errorf("data = %q, want hello", data)+ }+}++func TestDecodeHTMLImageSourceRejectsInvalidAndOversizedHeaders(t *testing.T) {+ for _, src := range []string{+ "data:image/png;base64,",+ "data:image/png;base64,YQ=",+ "data:image/png;base64,YQ===",+ "data:image/png;base64,G0==JbjQ",+ "data:image/png;" + strings.Repeat("x", 200) + ",aGVsbG8=",+ } {+ if _, _, ok := DecodeHTMLImageSource(src); ok {+ t.Errorf("DecodeHTMLImageSource(%q) succeeded", src)+ }+ }+}++func TestNormalizeHTMLImageSourceMatchesDecode(t *testing.T) {+ src := "data:image/png;base64,aGVs\nbG8"+ normalized, size, normalizedSum, ok := NormalizeHTMLImageSource(src)+ if !ok {+ t.Fatal("NormalizeHTMLImageSource rejected a valid payload")+ }+ mime, data, ok := DecodeHTMLImageSource(src)+ if !ok {+ t.Fatal("DecodeHTMLImageSource rejected a valid payload")+ }+ if normalized != "data:image/png;base64,aGVsbG8=" {+ t.Fatalf("normalized = %q", normalized)+ }+ decodeSum := sha256.Sum256(data)+ if size != int64(len(data)) || normalizedSum != decodeSum || mime != "image/png" {+ t.Fatalf("normalize/decode disagree: size=%d decodeSize=%d sum=%x decodeSum=%x mime=%q",+ size, len(data), normalizedSum, decodeSum, mime)+ }+}++func TestHTMLImageExceedsConfiguredLimit(t *testing.T) {+ t.Setenv("RAGFLOW_HTML_IMAGE_MAX_BYTES", "5")+ for _, tc := range []struct {+ src string+ want bool+ }{+ {"data:image/png;base64,aGVsbG8=", false},+ {"data:image/png;base64,aGVsbG8", false},+ {"data:image/png;base64,aGVsbG8h", true},+ {"data:image/png;base64,YQ==", false},+ } {+ if got := HTMLImageExceedsLimit(tc.src); got != tc.want {+ t.Errorf("%q: got %v, want %v", tc.src, got, tc.want)+ }+ }+}++func TestHTMLImageLimitDefaultsAndConfiguration(t *testing.T) {+ t.Setenv("RAGFLOW_HTML_IMAGE_MAX_BYTES", "")+ if got := HTMLImageMaxBytes(); got != 32<<20 {+ t.Fatalf("default = %d", got)+ }+ t.Setenv("RAGFLOW_HTML_IMAGE_MAX_BYTES", "67108864")+ if got := HTMLImageMaxBytes(); got != 64<<20 {+ t.Fatalf("configured = %d", got)+ }+}diff --git a/internal/parser/media/payload.go b/internal/parser/media/payload.gonew file mode 100644index 0000000000..c2bf0de54e--- /dev/null+++ b/internal/parser/media/payload.go@@ -0,0 +1,135 @@+//+// 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.+//++package media++import (+ "crypto/sha256"+ "encoding/base64"+ "io"+ "strings"+)++const (+ // MaxImagePayloadBytes bounds compressed image data accepted by media paths.+ MaxImagePayloadBytes = 32 << 20+ // maxStreamBuffer caps the copy buffer used while validating a payload.+ maxStreamBuffer = 32 << 10+)++// NormalizeBase64ImagePayload validates an external image payload within its+// decoded byte limit and returns standard base64 with padding, no CR/LF, the+// decoded byte count, and the digest of the decoded bytes. Validation streams+// the payload instead of retaining a decoded image buffer, so the parser's+// normalization path can hash every image without holding the decoded bytes.+func NormalizeBase64ImagePayload(payload string, maxDecodedBytes int) (string, int64, [sha256.Size]byte, bool) {+ var sum [sha256.Size]byte+ payload, ok := cleanBase64ImagePayload(payload, maxDecodedBytes)+ if !ok {+ return "", 0, sum, false+ }+ decoder := base64.NewDecoder(base64.StdEncoding, strings.NewReader(payload))+ hasher := sha256.New()+ limit := int64(maxDecodedBytes) + 1+ // io.CopyN would allocate a fresh 32 KiB buffer for every image, which+ // dominates both the parser and the fallback index walk on documents made+ // of small images. Size the copy buffer to the decoded payload instead.+ bufSize := int64(len(payload)/4*3) + 1+ if bufSize > maxStreamBuffer {+ bufSize = maxStreamBuffer+ }+ decodedBytes, err := io.CopyBuffer(io.MultiWriter(io.Discard, hasher), io.LimitReader(decoder, limit), make([]byte, bufSize))+ if err != nil || decodedBytes == 0 || decodedBytes > int64(maxDecodedBytes) {+ return "", 0, sum, false+ }+ copy(sum[:], hasher.Sum(nil))+ return payload, decodedBytes, sum, true+}++// decodeBase64ImagePayload validates and decodes one payload in a single+// pass, for callers that need the bytes. Digest calculation belongs to the+// media cache that stores those bytes.+func decodeBase64ImagePayload(payload string, maxDecodedBytes int) ([]byte, bool) {+ payload, ok := cleanBase64ImagePayload(payload, maxDecodedBytes)+ if !ok {+ return nil, false+ }+ data, err := base64.StdEncoding.DecodeString(payload)+ if err != nil || len(data) == 0 || len(data) > maxDecodedBytes {+ return nil, false+ }+ return data, true+}++// cleanBase64ImagePayload applies the shared length/padding validation and+// returns the payload in the form both the streaming and one-shot decoders+// accept.+func cleanBase64ImagePayload(payload string, maxDecodedBytes int) (string, bool) {+ if maxDecodedBytes < 0 {+ return "", false+ }+ encodedBytes, ok := scanBase64ImagePayload(payload, base64.StdEncoding.EncodedLen(maxDecodedBytes))+ if !ok {+ return "", false+ }+ payload = strings.ReplaceAll(payload, "\r", "")+ payload = strings.ReplaceAll(payload, "\n", "")+ if remainder := encodedBytes % 4; remainder != 0 {+ payload += strings.Repeat("=", 4-remainder)+ }+ return payload, true+}++// scanBase64ImagePayload counts the base64 characters of an image payload+// (CR/LF excluded) and rejects a payload whose padding is malformed: '=' may+// only appear in the final quantum, at most twice, and the character count+// must form whole quanta.+//+// The padding rule is what rejects data that follows a padded quantum. Go's+// streaming decoder only reports that when the whole payload lands in one+// decode call, so it cannot be left to the decoder.+func scanBase64ImagePayload(payload string, maxEncodedBytes int) (int, bool) {+ encodedBytes := 0+ padding := 0+ sawPadding := false+ for i := 0; i < len(payload); i++ {+ if payload[i] == '\r' || payload[i] == '\n' {+ continue+ }+ encodedBytes+++ if encodedBytes > maxEncodedBytes {+ return 0, false+ }+ if payload[i] == '=' {+ sawPadding = true+ padding+++ if padding > 2 {+ return 0, false+ }+ continue+ }+ if sawPadding {+ return 0, false+ }+ }+ if encodedBytes == 0 {+ return 0, false+ }+ if encodedBytes%4 == 1 || (padding > 0 && encodedBytes%4 != 0) {+ return 0, false+ }+ return encodedBytes, true+}diff --git a/internal/parser/media/payload_test.go b/internal/parser/media/payload_test.gonew file mode 100644index 0000000000..9b6290d604--- /dev/null+++ b/internal/parser/media/payload_test.go@@ -0,0 +1,80 @@+// 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.++package media++import (+ "bytes"+ "crypto/sha256"+ "encoding/base64"+ "testing"+)++func TestNormalizeBase64ImagePayloadByteLimit(t *testing.T) {+ for _, tc := range []struct {+ name, payload string+ limit int+ want string+ wantSize int64+ }{+ {"negative_limit", "YQ", -1, "", 0},+ {"zero_limit", "YQ", 0, "", 0},+ {"exact_limit_padded", "YWI=", 2, "YWI=", 2},+ {"exact_limit_unpadded", "YWI", 2, "YWI=", 2},+ {"exact_limit_wrapped", "YW\r\nI", 2, "YWI=", 2},+ {"over_limit_padded", "YWI=", 1, "", 0},+ {"over_limit_unpadded", "YWI", 1, "", 0},+ {"over_encoded_limit", "YWJjZA==", 2, "", 0},+ {"data_after_padding", "G0==JbjQ", 16, "", 0},+ {"data_after_padding_long", "aMRFPqfZALtY6rw50P==Pn5d", 16, "", 0},+ } {+ t.Run(tc.name, func(t *testing.T) {+ got, size, _, ok := NormalizeBase64ImagePayload(tc.payload, tc.limit)+ if got != tc.want || ok != (tc.want != "") || size != tc.wantSize {+ t.Errorf("NormalizeBase64ImagePayload(%q, %d) = (%q, %d, %v), want (%q, %d, %v)",+ tc.payload, tc.limit, got, size, ok, tc.want, tc.wantSize, tc.want != "")+ }+ })+ }+}++func TestDecodeBase64ImagePayloadMatchesNormalize(t *testing.T) {+ for _, payload := range []string{+ "YQ==", "YQ", "YWJj", "YW\r\nJj", "YWI=",+ "", "Y?==", "YQ=", "YQ===", "Y=Q=", "Y", "G0==JbjQ",+ } {+ normalized, size, wantSum, ok := NormalizeBase64ImagePayload(payload, 16)+ data, decodeOK := decodeBase64ImagePayload(payload, 16)+ if ok != decodeOK {+ t.Errorf("payload %q: normalize ok=%v, decode ok=%v", payload, ok, decodeOK)+ continue+ }+ if !ok {+ continue+ }+ want, err := base64.StdEncoding.DecodeString(normalized)+ if err != nil {+ t.Fatalf("normalized payload %q does not decode: %v", normalized, err)+ }+ if !bytes.Equal(data, want) {+ t.Errorf("payload %q: decoded %q, want %q", payload, data, want)+ }+ if int64(len(data)) != size {+ t.Errorf("payload %q: size = %d, want %d", payload, len(data), size)+ }+ if sha256.Sum256(data) != wantSum {+ t.Errorf("payload %q: digest mismatch", payload)+ }+ }+}diff --git a/internal/parser/parser/csv_parser.go b/internal/parser/parser/csv_parser.goindex 92952e50ec..5f77176e5a 100644--- a/internal/parser/parser/csv_parser.go+++ b/internal/parser/parser/csv_parser.go@@ -29,6 +29,8 @@ import ("fmt""strings""unicode/utf8"++ "ragflow/internal/parser/charset")const csvSheetName = "Data"@@ -111,7 +113,7 @@ func (p *CSVParser) ParseWithResult(ctx context.Context, filename string, data [// for CSV processing.}- decoded, encName := DecodeToUTF8(data, "text/csv")+ decoded, encName := charset.DecodeToUTF8(data, "text/csv")text := string(decoded)if strings.TrimSpace(text) == "" {return ParseResult{diff --git a/internal/parser/parser/csv_parser_test.go b/internal/parser/parser/csv_parser_test.goindex ab7ee95cdf..eace88d521 100644--- a/internal/parser/parser/csv_parser_test.go+++ b/internal/parser/parser/csv_parser_test.go@@ -6,6 +6,8 @@ import ("reflect""strings""testing"++ "golang.org/x/text/encoding/simplifiedchinese")func TestCSVParser_EmitsSpreadsheetRows(t *testing.T) {@@ -294,3 +296,36 @@ func TestCSVParser_PreservesInternalJoiners(t *testing.T) {t.Errorf("Persian half-space lost: %q", text)}}++func TestCSVParser_GBK(t *testing.T) {+ csvText := "产品,分类,价格,备注\n笔记本电脑,电子,6999.00,\"特价销售,送鼠标\"\n无线耳机,配件,399.00,\"热销\"\n"+ gbkBytes, err := simplifiedchinese.GBK.NewEncoder().Bytes([]byte(csvText))+ if err != nil {+ t.Fatalf("GBK encode: %v", err)+ }++ p := NewCSVParser()+ res := p.ParseWithResult(context.Background(), "products.csv", gbkBytes)+ if res.Err != nil {+ t.Fatalf("CSVParser.ParseWithResult failed: %v", res.Err)+ }+ if len(res.JSON) == 0 {+ t.Fatalf("CSVParser returned no JSON items")+ }+ var rowText strings.Builder+ for _, item := range ItemsToMaps(res.JSON) {+ text := tableItemHTML(t, item)+ rowText.WriteString(text)+ }+ if strings.ContainsRune(rowText.String(), '\ufffd') {+ t.Errorf("CSV output contains replacement runes: %s", rowText.String())+ }+ for _, want := range []string{"笔记本电脑", "电子", "特价销售,送鼠标", "无线耳机"} {+ if !strings.Contains(rowText.String(), want) {+ t.Errorf("CSV output missing expected substring %q; got: %s", want, rowText.String())+ }+ }+ if enc, _ := res.File["encoding"].(string); enc != "gb18030" && enc != "gbk" && enc != "gb2312" {+ t.Errorf("CSV File.encoding = %q, want gbk/gb2312/gb18030", enc)+ }+}diff --git a/internal/parser/parser/doc_item.go b/internal/parser/parser/doc_item.goindex 29fa18dc18..fb1d79efcd 100644--- a/internal/parser/parser/doc_item.go+++ b/internal/parser/parser/doc_item.go@@ -77,11 +77,13 @@ func (t TableItem) ToMap() map[string]any {}// ImageItem is an embedded image. Text is the alt text, Image the data-// URL/base64 payload (possibly empty when omitted). Parsers emit standard-// base64 with padding and no CR/LF in the payload.+// URL/base64 payload (possibly empty when the parser emitted only a+// MediaRef). Parsers emit standard base64 with padding and no CR/LF in the+// payload.type ImageItem struct {Text stringImage string+ Media *entity.MediaRefSheet stringPositions PositionsExtra map[string]any@@ -90,9 +92,18 @@ type ImageItem struct {func (i ImageItem) ToMap() map[string]any {m := map[string]any{"text": i.Text,- "image": i.Image,DocTypeKey: DocTypeImage,}+ // A ref-only image must not resurrect an empty "image" key: consumers use+ // the key's absence to tell deferred bytes from an inline payload. Any+ // present reference is emitted even when malformed, so the materializer+ // can reject it instead of the conversion dropping it.+ if i.Image != "" || i.Media == nil {+ m["image"] = i.Image+ }+ if i.Media != nil {+ m["media_ref"] = i.Media+ }if i.Sheet != "" {m["sheet"] = i.Sheet}@@ -161,6 +172,9 @@ func DocItemFromMap(m map[string]any) DocItem {if _, ok := m["image"]; ok {return imageItemFromMap(m)}+ if entity.MediaRefFromAny(m["media_ref"]) != nil {+ return imageItemFromMap(m)+ }return RawItem{M: m}case DocTypeTable:if _, ok := m["table"]; ok {@@ -181,7 +195,11 @@ func textItemFromMap(m map[string]any) DocItem {func imageItemFromMap(m map[string]any) DocItem {pos := wireToPositions(m["positions"], hasSheetIndex(m))+ media := entity.MediaRefFromAny(m["media_ref"])skip := []string{"text", "image", DocTypeKey, "sheet"}+ if media != nil {+ skip = append(skip, "media_ref")+ }if pos != nil {// Parsed into the typed field: it owns "positions", so strip it from// Extra. Both [][]float64 (office/xlsx) and [][]any (PDF crop regions@@ -192,6 +210,7 @@ func imageItemFromMap(m map[string]any) DocItem {return ImageItem{Text: stringField(m, "text"),Image: stringField(m, "image"),+ Media: media,Sheet: stringField(m, "sheet"),Positions: pos,Extra: extraFromMap(m, skip...),diff --git a/internal/parser/parser/email_parser.go b/internal/parser/parser/email_parser.goindex 7397509b13..2254e39266 100644--- a/internal/parser/parser/email_parser.go+++ b/internal/parser/parser/email_parser.go@@ -35,6 +35,7 @@ import ("golang.org/x/text/transform""ragflow/internal/common"+ charsetlib "ragflow/internal/parser/charset""ragflow/internal/utility")@@ -174,7 +175,7 @@ func targetFieldsSet(fields []string) map[string]bool {// the non-UTF-8 charsets via charsetEncoding.var rfc2047Decoder = &mime.WordDecoder{CharsetReader: func(charset string, input io.Reader) (io.Reader, error) {- if enc, ok := charsetEncoding(charset); ok {+ if enc, ok := charsetlib.CharsetEncoding(charset); ok {return transform.NewReader(input, enc.NewDecoder()), nil}return nil, fmt.Errorf("email: unsupported header charset %q", charset)@@ -409,7 +410,7 @@ func decodeMailPayload(payload []byte, charset string) string {if len(payload) == 0 {return ""}- decoded, _ := DecodeToUTF8(payload, charset)+ decoded, _ := charsetlib.DecodeToUTF8(payload, charset)return string(decoded)}@@ -682,6 +683,9 @@ func (p *EmailParser) rechunkEmailAttachments(ctx context.Context, content map[sif err != nil {continue}+ if ft == utility.FileTypeHTML {+ np = NewHTMLTextParser()+ }res, panicked = recoverParse(func() ParseResult {return np.ParseWithResult(ctx, fn, []byte(payload))})diff --git a/internal/parser/parser/email_parser_test.go b/internal/parser/parser/email_parser_test.goindex bc68110952..0d803d3691 100644--- a/internal/parser/parser/email_parser_test.go+++ b/internal/parser/parser/email_parser_test.go@@ -450,6 +450,43 @@ func TestEmailParser_Base64Attachment(t *testing.T) {}}+func TestEmailParser_HTMLAttachmentDoesNotCacheMedia(t *testing.T) {+ const boundary = "html-media-boundary"+ attachment := `<html><body><p>Embedded figure</p><img alt="attachment image" src="` ++ htmlMediaDataURI + `"></body></html>`+ raw := strings.Join([]string{+ "From: [email protected]",+ "To: [email protected]",+ "Subject: HTML attachment",+ "Content-Type: multipart/mixed; boundary=" + boundary,+ "",+ "--" + boundary,+ "Content-Type: text/plain; charset=utf-8",+ "",+ "Outer body.",+ "--" + boundary,+ "Content-Type: text/html; charset=utf-8; name=\"embedded.html\"",+ "Content-Disposition: attachment; filename=\"embedded.html\"",+ "Content-Transfer-Encoding: base64",+ "",+ base64.StdEncoding.EncodeToString([]byte(attachment)),+ "--" + boundary + "--",+ }, "\r\n")++ p := NewEmailParser()+ p.ConfigureFromSetup(map[string]any{+ "fields": []string{"from", "body", "attachments"},+ })+ ctx, cache := recordingMediaContext()+ result := p.ParseWithResult(ctx, "message.eml", []byte(raw))+ if result.Err != nil {+ t.Fatalf("ParseWithResult: %v", result.Err)+ }+ if cache.putCalls != 0 {+ t.Fatalf("unexpected media cache writes = %d", cache.putCalls)+ }+}+func TestEmailParser_Base64AttachmentInMixedMultipart(t *testing.T) {ctx := t.Context()// Simulates the original test email structure:@@ -1397,3 +1434,32 @@ func TestEmailParserTextOutputRemoved(t *testing.T) {}}}++func TestEmailParser_HTMLAttachmentTextWithoutMediaCache(t *testing.T) {+ const boundary = "embedded-html"+ attachment := `<p>before figure</p><img src="data:image/png;base64,aGVsbG8="><p>after figure</p>`+ raw := strings.Join([]string{+ "From: [email protected]", "To: [email protected]", "Subject: HTML attachment",+ "Content-Type: multipart/mixed; boundary=" + boundary, "",+ "--" + boundary, "Content-Type: text/plain; charset=utf-8", "", "Outer body.",+ "--" + boundary, "Content-Type: text/html; charset=utf-8; name=\"embedded.html\"",+ "Content-Disposition: attachment; filename=\"embedded.html\"", "Content-Transfer-Encoding: base64", "",+ base64.StdEncoding.EncodeToString([]byte(attachment)), "--" + boundary + "--",+ }, "\r\n")+ p := NewEmailParser()+ p.ConfigureFromSetup(map[string]any{"fields": []string{"from", "body", "attachments"}})+ result := p.ParseWithResult(t.Context(), "message.eml", []byte(raw))+ if result.Err != nil {+ t.Fatal(result.Err)+ }+ var texts []string+ for _, item := range result.JSON {+ if text, ok := item.ToMap()["text"].(string); ok {+ texts = append(texts, text)+ }+ }+ joined := strings.Join(texts, "\n")+ if !strings.Contains(joined, "before figure") || !strings.Contains(joined, "after figure") {+ t.Fatalf("attachment text missing: %q", joined)+ }+}diff --git a/internal/parser/parser/epub_parser.go b/internal/parser/parser/epub_parser.goindex df2ac36922..e7398491c7 100644--- a/internal/parser/parser/epub_parser.go+++ b/internal/parser/parser/epub_parser.go@@ -40,6 +40,8 @@ import ("strings""golang.org/x/net/html"++ "ragflow/internal/parser/charset")// EPUBParser extracts text from EPUB archives.@@ -222,7 +224,7 @@ func extractEPUBTextItems(r *zip.Reader, opfDir string, spineHrefs []string) ([]continue}read++- decoded, enc := DecodeToUTF8(raw, "application/xhtml+xml")+ decoded, enc := charset.DecodeToUTF8(raw, "application/xhtml+xml")if detectedEncoding == "utf-8" && enc != "" && enc != "utf-8" {detectedEncoding = enc}diff --git a/internal/parser/parser/epub_parser_test.go b/internal/parser/parser/epub_parser_test.goindex f1603bf8ef..1fbc76f8e2 100644--- a/internal/parser/parser/epub_parser_test.go+++ b/internal/parser/parser/epub_parser_test.go@@ -23,6 +23,8 @@ import ("fmt""strings""testing"++ "golang.org/x/text/encoding/simplifiedchinese")// epubTestChapter is one spine item of a test EPUB. A missing chapter is@@ -302,3 +304,51 @@ func TestEPUBParserPreservesChapterTextUnits(t *testing.T) {t.Fatalf("second chapter text=%q, want %q", got, want)}}++func TestEPUBParser_GB2312(t *testing.T) {+ // Create an in-memory EPUB zip with GB2312-encoded chapter XHTML+ chapterContent := `<?xml version="1.0" encoding="GB2312"?>+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">+<html xmlns="http://www.w3.org/1999/xhtml">+<head><title>第一章</title></head>+<body><h1>第一章 破晓</h1><p>这是一段包含中文的EPUB正文内容。</p></body>+</html>`+ chapterGBK, err := simplifiedchinese.GBK.NewEncoder().Bytes([]byte(chapterContent))+ if err != nil {+ t.Fatalf("GBK encode: %v", err)+ }++ containerXML := `<?xml version="1.0"?><container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container"><rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles></container>`+ contentOPF := `<?xml version="1.0" encoding="utf-8"?><package xmlns="http://www.idpf.org/2007/opf" unique-identifier="BookID" version="2.0"><metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:title>测试</dc:title></metadata><manifest><item id="c1" href="c1.xhtml" media-type="application/xhtml+xml"/></manifest><spine><itemref idref="c1"/></spine></package>`++ buf := new(bytes.Buffer)+ zw := zip.NewWriter(buf)+ w, _ := zw.Create("META-INF/container.xml")+ w.Write([]byte(containerXML))+ w, _ = zw.Create("OEBPS/content.opf")+ w.Write([]byte(contentOPF))+ w, _ = zw.Create("OEBPS/c1.xhtml")+ w.Write(chapterGBK)+ zw.Close()++ p := NewEPUBParser()+ res := p.ParseWithResult(context.Background(), "book.epub", buf.Bytes())+ if res.Err != nil {+ t.Fatalf("EPUBParser.ParseWithResult failed: %v", res.Err)+ }+ if len(res.JSON) == 0 {+ t.Fatal("want non-empty JSON items from EPUB")+ }+ text := epubTestText(res)+ if strings.ContainsRune(text, '\ufffd') {+ t.Errorf("EPUB text contains replacement runes: %s", text)+ }+ for _, want := range []string{"第一章 破晓", "这是一段包含中文的EPUB正文内容。"} {+ if !strings.Contains(text, want) {+ t.Errorf("EPUB text missing %q; got: %s", want, text)+ }+ }+ if enc, _ := res.File["encoding"].(string); enc != "gb2312" && enc != "gbk" && enc != "gb18030" {+ t.Errorf("EPUB File.encoding = %q, want gb2312/gbk/gb18030", enc)+ }+}diff --git a/internal/parser/parser/html_media_test.go b/internal/parser/parser/html_media_test.goindex 9950e39551..c728c0a082 100644--- a/internal/parser/parser/html_media_test.go+++ b/internal/parser/parser/html_media_test.go@@ -2,16 +2,116 @@ package parserimport ("context"+ "crypto/sha256""encoding/base64"+ "encoding/hex"+ "encoding/json"+ "errors""strings""testing"++ "ragflow/internal/entity"+ "ragflow/internal/parser/media")const htmlMediaDataURI = "data:image/png;base64,aGVsbG8="-func TestHTMLParser_EmitsInlineImagesInDocumentOrder(t *testing.T) {+type recordingMediaCache struct {+ puts []recordingMediaPut+ putErr error+ getData map[string][]byte+ putCalls int+}++type recordingMediaPut struct {+ format string+ mime string+ data []byte+}++func (c *recordingMediaCache) Put(_ context.Context, format, mime string, data []byte) (entity.MediaRef, error) {+ c.putCalls+++ c.puts = append(c.puts, recordingMediaPut{format: format, mime: mime, data: append([]byte(nil), data...)})+ if c.putErr != nil {+ return entity.MediaRef{}, c.putErr+ }+ sum := sha256.Sum256(data)+ ref := entity.MediaRef{+ Format: format,+ Kind: entity.MediaKindKV,+ Scope: "run-1",+ SHA256: hex.EncodeToString(sum[:]),+ MIME: mime,+ Size: int64(len(data)),+ }+ if c.getData == nil {+ c.getData = map[string][]byte{}+ }+ c.getData[ref.SHA256] = append([]byte(nil), data...)+ return ref, nil+}++func (c *recordingMediaCache) Get(_ context.Context, ref entity.MediaRef) ([]byte, error) {+ data, ok := c.getData[ref.SHA256]+ if !ok {+ return nil, media.ErrMediaNotFound+ }+ return append([]byte(nil), data...), nil+}++func recordingMediaContext() (context.Context, *recordingMediaCache) {+ cache := &recordingMediaCache{}+ return media.WithCache(context.Background(), cache), cache+}++func TestHTMLParser_WritesImageToRunScopedMediaCache(t *testing.T) {+ cache := &recordingMediaCache{}+ ctx := media.WithCache(context.Background(), cache)+ result := NewHTMLParser().ParseWithResult(ctx, "cached.html", []byte(`<img alt="figure" src="`+htmlMediaDataURI+`">`))+ if result.Err != nil {+ t.Fatalf("ParseWithResult: %v", result.Err)+ }+ if cache.putCalls != 1 || len(cache.puts) != 1 {+ t.Fatalf("cache Put calls = %d/%d, want 1/1", cache.putCalls, len(cache.puts))+ }+ if cache.puts[0].format != "html" || cache.puts[0].mime != "image/png" || string(cache.puts[0].data) != "hello" {+ t.Fatalf("cache Put = %+v", cache.puts[0])+ }+ item := result.JSON[0].ToMap()+ ref := entity.MediaRefFromAny(item["media_ref"])+ if ref == nil || ref.Kind != entity.MediaKindKV || ref.Scope != "run-1" {+ t.Fatalf("media_ref = %+v", ref)+ }+ if _, ok := item["image"]; ok {+ t.Fatalf("image bytes retained: %+v", item)+ }+ encoded, err := json.Marshal(result.JSON)+ if err != nil {+ t.Fatal(err)+ }+ if !strings.Contains(string(encoded), `"scope":"run-1"`) {+ t.Fatalf("serialized media_ref lost scope: %s", encoded)+ }+}++func TestHTMLParser_FailsWhenMediaCacheWriteFails(t *testing.T) {+ writeErr := errors.New("kvrocks unavailable")+ cache := &recordingMediaCache{putErr: writeErr}+ ctx := media.WithCache(context.Background(), cache)+ input := `<img src="` + htmlMediaDataURI + `"><img src="` + htmlMediaDataURI + `">`+ result := NewHTMLParser().ParseWithResult(ctx, "failed.html", []byte(input))+ if !errors.Is(result.Err, writeErr) {+ t.Fatalf("ParseWithResult error = %v, want %v", result.Err, writeErr)+ }+ if cache.putCalls != 1 {+ t.Fatalf("cache Put calls = %d, want traversal to stop after the first failure", cache.putCalls)+ }+}++func TestHTMLParser_EmitsMediaRefsInDocumentOrder(t *testing.T) {input := `<p>before <img alt="figure alt" src="` + htmlMediaDataURI + `"> after</p>`- result := NewHTMLParser().ParseWithResult(context.Background(), "inline.html", []byte(input))+ ctx, _ := recordingMediaContext()+ result := NewHTMLParser().ParseWithResult(ctx, "inline.html", []byte(input))if result.Err != nil {t.Fatalf("ParseWithResult: %v", result.Err)}@@ -25,9 +125,15 @@ func TestHTMLParser_EmitsInlineImagesInDocumentOrder(t *testing.T) {t.Errorf("before item = %+v", result.JSON[0])}imageItem := result.JSON[1].ToMap()- if imageItem["doc_type_kwd"] != "image" || imageItem["image"] != htmlMediaDataURI || imageItem["text"] != "figure alt" || imageItem["media_order"] != 1 {+ if imageItem["doc_type_kwd"] != "image" || imageItem["text"] != "figure alt" || imageItem["media_order"] != 1 {t.Errorf("image item = %+v", imageItem)}+ if _, ok := imageItem["image"]; ok {+ t.Errorf("image bytes retained: %+v", imageItem)+ }+ if entity.MediaRefFromAny(imageItem["media_ref"]) == nil {+ t.Errorf("image item without media_ref: %+v", imageItem)+ }if result.JSON[2].ToMap()["text"] != "after" || result.JSON[2].ToMap()["doc_type_kwd"] != "text" {t.Errorf("after item = %+v", result.JSON[2])}@@ -35,7 +141,8 @@ func TestHTMLParser_EmitsInlineImagesInDocumentOrder(t *testing.T) {func TestHTMLParser_EmitsTableCellImagesWithParentAndCellOrder(t *testing.T) {input := `<table><tr><td>A<img alt="first" src="` + htmlMediaDataURI + `"></td><td><img src="https://example.com/second.png"></td></tr></table>`- result := NewHTMLParser().ParseWithResult(context.Background(), "table.html", []byte(input))+ ctx, _ := recordingMediaContext()+ result := NewHTMLParser().ParseWithResult(ctx, "table.html", []byte(input))if result.Err != nil {t.Fatalf("ParseWithResult: %v", result.Err)}@@ -52,10 +159,13 @@ func TestHTMLParser_EmitsTableCellImagesWithParentAndCellOrder(t *testing.T) {if !strings.Contains(tableText, "A") {t.Errorf("table text lost the cell text: %q", tableText)}- if result.JSON[1].ToMap()["image"] != htmlMediaDataURI {- t.Errorf("inline image payload = %v, want data URI", result.JSON[1].ToMap()["image"])- }item := result.JSON[1].ToMap()+ if _, ok := item["image"]; ok {+ t.Errorf("image bytes retained: %+v", item)+ }+ if entity.MediaRefFromAny(item["media_ref"]) == nil {+ t.Errorf("image item without media_ref: %+v", item)+ }if item["doc_type_kwd"] != "image" || item["parent_table_id"] != "html-table-1" {t.Errorf("inline image item = %+v", item)}@@ -64,39 +174,257 @@ func TestHTMLParser_EmitsTableCellImagesWithParentAndCellOrder(t *testing.T) {}}-func TestHTMLParser_RejectsOversizedInlineImagePayload(t *testing.T) {- payload := base64.StdEncoding.EncodeToString(make([]byte, maxEmbeddedImageBytes+1))- input := "<p><img alt=\"large\" src=\"data:image/png;base64," + payload + "\"></p>"- result := NewHTMLParser().ParseWithResult(context.Background(), "large.html", []byte(input))+func TestHTMLParser_SkipsOversizedInlineImagePayload(t *testing.T) {+ t.Setenv("RAGFLOW_HTML_IMAGE_MAX_BYTES", "4")+ for name, oversized := range map[string]string{+ "inline": `<p><img src="` + htmlMediaDataURI + `"></p>`,+ "table": `<table><tr><td><img src="` + htmlMediaDataURI + `"></td></tr></table>`,+ } {+ t.Run(name, func(t *testing.T) {+ ctx, cache := recordingMediaContext()+ input := oversized + `<p>after <img src="data:image/png;base64,YQ=="></p>`+ result := NewHTMLParser().ParseWithResult(ctx, "large.html", []byte(input))+ if result.Err != nil {+ t.Fatalf("ParseWithResult: %v", result.Err)+ }+ if cache.putCalls != 1 || string(cache.puts[0].data) != "a" {+ t.Fatalf("cached images = %+v, want only the smaller image", cache.puts)+ }+ if !strings.Contains(renderedText(result.JSON[len(result.JSON)-2].ToMap()), "after") {+ t.Fatalf("text after oversized image lost: %+v", result.JSON)+ }+ if !strings.Contains(strings.Join(result.Warnings, " "), "invalid or oversized inline image") {+ t.Fatalf("missing skipped-image warning: %v", result.Warnings)+ }+ })+ }+}++func TestHTMLParser_HasNoParserSideImageCountLimit(t *testing.T) {+ const count = maxEmbeddedMediaItems + 44+ input := "<p>" + strings.Repeat(`<img src="`+htmlMediaDataURI+`">`, count) + "</p>"+ ctx, _ := recordingMediaContext()+ result := NewHTMLParser().ParseWithResult(ctx, "many.html", []byte(input))if result.Err != nil {t.Fatalf("ParseWithResult: %v", result.Err)}- for _, item := range ItemsToMaps(result.JSON) {- if item["doc_type_kwd"] == "image" {- t.Fatal("oversized data URI emitted as an image item")+ images := 0+ for _, item := range result.JSON {+ if item.ToMap()["doc_type_kwd"] == "image" {+ images++}}- if len(result.Warnings) == 0 {- t.Fatal("oversized inline image should produce a parser warning")+ if images != count {+ t.Fatalf("images = %d, want %d (no parser-side cap, matching PDF)", images, count)+ }+ if strings.Contains(strings.Join(result.Warnings, "\n"), "256-item") {+ t.Fatalf("unexpected parser-side image cap warning: %v", result.Warnings)+ }+}++func TestHTMLParser_EmitsMediaRef(t *testing.T) {+ p := NewHTMLParser()+ ctx, _ := recordingMediaContext()+ result := p.ParseWithResult(ctx, "ref.html", []byte(`<p><img alt="figure" src="`+htmlMediaDataURI+`"></p>`))+ if result.Err != nil {+ t.Fatalf("ParseWithResult: %v", result.Err)+ }+ item := result.JSON[0].ToMap()+ if _, ok := item["image"]; ok {+ t.Fatalf("image bytes retained: %+v", item)+ }+ ref := entity.MediaRefFromAny(item["media_ref"])+ if ref == nil {+ t.Fatalf("missing media_ref: %+v", item)+ }+ if ref.Format != "html" || ref.Kind != entity.MediaKindKV || ref.Scope != "run-1" || ref.MIME != "image/png" || ref.Size != int64(len("hello")) {+ t.Fatalf("media_ref = %+v", ref)+ }+ sum := sha256.Sum256([]byte("hello"))+ if want := hex.EncodeToString(sum[:]); ref.SHA256 != want {+ t.Fatalf("sha256 = %s, want %s", ref.SHA256, want)}}-func TestHTMLParser_DocumentImageLimit(t *testing.T) {- input := "<p>" + strings.Repeat(`<img src="`+htmlMediaDataURI+`">`, maxEmbeddedMediaItems+44) + "</p>"- result := NewHTMLParser().ParseWithResult(context.Background(), "many.html", []byte(input))+func TestParserMediaRefsResolveFromRunCache(t *testing.T) {+ input := `<p>before <img src="` + htmlMediaDataURI + `"></p>` ++ `<table><tr><td><img alt="cell" src="` + htmlMediaDataURI + `"></td></tr></table>`+ ctx, cache := recordingMediaContext()+ result := NewHTMLParser().ParseWithResult(ctx, "match.html", []byte(input))if result.Err != nil {t.Fatalf("ParseWithResult: %v", result.Err)}images := 0+ for _, item := range result.JSON {+ m := item.ToMap()+ if m["doc_type_kwd"] != DocTypeImage {+ continue+ }+ images+++ ref := entity.MediaRefFromAny(m["media_ref"])+ if ref == nil {+ t.Fatalf("image item without ref: %+v", m)+ }+ data, err := cache.Get(ctx, *ref)+ if err != nil {+ t.Fatalf("resolve image %d: %v", images, err)+ }+ sum := sha256.Sum256(data)+ if got := hex.EncodeToString(sum[:]); got != ref.SHA256 {+ t.Fatalf("image %d digest = %s, want %s", images, got, ref.SHA256)+ }+ }+ if images != 2 {+ t.Fatalf("image items = %d, want 2", images)+ }+}++func TestHTMLParser_ResultIndependentOfImageBytes(t *testing.T) {+ const imageCount = 64+ payload := base64.StdEncoding.EncodeToString(make([]byte, 64<<10))+ input := strings.Repeat(`<img src="data:image/png;base64,`+payload+`">`, imageCount)++ p := NewHTMLParser()+ ctx, _ := recordingMediaContext()+ result := p.ParseWithResult(ctx, "large.html", []byte(input))+ if result.Err != nil {+ t.Fatalf("ParseWithResult: %v", result.Err)+ }+ items := 0for _, item := range result.JSON {if item.ToMap()["doc_type_kwd"] == "image" {- images+++ items++}}- if images != maxEmbeddedMediaItems {- t.Fatalf("images = %d, want document limit %d", images, maxEmbeddedMediaItems)+ if items != imageCount {+ t.Fatalf("image items = %d, want %d", items, imageCount)+ }+ encoded, err := json.Marshal(result.JSON)+ if err != nil {+ t.Fatalf("marshal result: %v", err)+ }+ // 64 refs are a few KB; the inline form would be over 4 MB.+ if len(encoded) > 256<<10 {+ t.Fatalf("ref-mode result is %d bytes; it must not scale with image payloads", len(encoded))}- if !strings.Contains(strings.Join(result.Warnings, "\n"), "256-item document limit") {- t.Fatalf("missing document image limit warning: %v", result.Warnings)+}++// TestHTMLMediaCacheMatchesParserAttributeSemantics pins that the bytes sent to+// Kvrocks come from the parser's decoded attribute value: entities in the media+// type, an encoded comma, a semicolon-less numeric reference, and an unquoted+// value ending in "/>".+func TestHTMLMediaCacheMatchesParserAttributeSemantics(t *testing.T) {+ cases := map[string]string{+ "entity in header": `<img src="data:image/png;base64,aGVsbG8=">`,+ "entity comma": `<img src="data:image/png;base64,aGVsbG8=">`,+ "semicolonless entity": `<img src="data:image/png;base64,aGVsbG8+">`,+ "unquoted trailing slash": `<img src=data:image/png;base64,aGVsbG8/>`,+ }+ for name, input := range cases {+ t.Run(name, func(t *testing.T) {+ p := NewHTMLParser()+ ctx, cache := recordingMediaContext()+ result := p.ParseWithResult(ctx, "case.html", []byte(input))+ if result.Err != nil {+ t.Fatal(result.Err)+ }+ var ref *entity.MediaRef+ for _, item := range result.JSON {+ m := item.ToMap()+ if m["doc_type_kwd"] != DocTypeImage {+ continue+ }+ ref = entity.MediaRefFromAny(m["media_ref"])+ }+ if ref == nil {+ t.Fatalf("parser emitted no media_ref: %+v", result.JSON)+ }+ data, err := cache.Get(ctx, *ref)+ if err != nil {+ t.Fatalf("resolver lost the parser's image: %v", err)+ }+ sum := sha256.Sum256(data)+ if got := hex.EncodeToString(sum[:]); got != ref.SHA256 {+ t.Fatalf("digest = %s, want %s", got, ref.SHA256)+ }+ })+ }+}++// TestHTMLMediaCacheIgnoresScriptDataURIs pins that image-like text inside a+// script is not written to the cache.+func TestHTMLMediaCacheIgnoresScriptDataURIs(t *testing.T) {+ img := `<img src="data:image/png;base64,aGVsbG8=">`+ input := "<script>" + strings.Repeat(img, 5000) + "</script>" + img++ p := NewHTMLParser()+ ctx, cache := recordingMediaContext()+ result := p.ParseWithResult(ctx, "script.html", []byte(input))+ if result.Err != nil {+ t.Fatal(result.Err)+ }+ var ref *entity.MediaRef+ for _, item := range result.JSON {+ m := item.ToMap()+ if m["doc_type_kwd"] == DocTypeImage {+ ref = entity.MediaRefFromAny(m["media_ref"])+ }+ }+ if ref == nil {+ t.Fatal("parser emitted no media_ref")+ }+ if _, err := cache.Get(ctx, *ref); err != nil {+ t.Fatalf("resolve: %v", err)+ }+}++// mediaRefFromHTML returns the first image reference the HTML parser emits.+func mediaRefFromHTML(t *testing.T, input string, cache *recordingMediaCache) *entity.MediaRef {+ t.Helper()+ p := NewHTMLParser()+ result := p.ParseWithResult(media.WithCache(context.Background(), cache), "case.html", []byte(input))+ if result.Err != nil {+ t.Fatal(result.Err)+ }+ var ref *entity.MediaRef+ for _, item := range result.JSON {+ m := item.ToMap()+ if m["doc_type_kwd"] == DocTypeImage {+ ref = entity.MediaRefFromAny(m["media_ref"])+ }+ }+ if ref == nil {+ t.Fatalf("parser emitted no media_ref: %+v", result.JSON)+ }+ return ref+}++func resolveMediaInput(t *testing.T, ref entity.MediaRef, cache *recordingMediaCache) []byte {+ t.Helper()+ data, err := cache.Get(context.Background(), ref)+ if err != nil {+ t.Fatalf("resolve: %v", err)+ }+ return data+}++func TestMediaResolverHandlesSelfClosingImg(t *testing.T) {+ input := `<img src="data:image/png;base64,aGVsbG8=" />`+ cache := &recordingMediaCache{}+ ref := mediaRefFromHTML(t, input, cache)+ if data := resolveMediaInput(t, *ref, cache); string(data) != "hello" {+ t.Fatalf("data = %q, want hello", data)+ }+}++func TestHTMLMediaCacheUsesParserDOM(t *testing.T) {+ // In the HTML tree builder <svg><title> is foreign content, so the <img>+ // becomes an element. The parser writes the image from its own DOM walk;+ // there is no second tokenizer or fallback scan.+ input := `<svg><title><img src="data:image/png;base64,aGVsbG8="></title></svg>`+ cache := &recordingMediaCache{}+ ref := mediaRefFromHTML(t, input, cache)+ if data := resolveMediaInput(t, *ref, cache); string(data) != "hello" {+ t.Fatalf("data = %q, want hello", data)}}diff --git a/internal/parser/parser/html_parser.go b/internal/parser/parser/html_parser.goindex 3989302f7d..908f5d959b 100644--- a/internal/parser/parser/html_parser.go+++ b/internal/parser/parser/html_parser.go@@ -23,18 +23,28 @@ import ("strings""golang.org/x/net/html"++ "ragflow/internal/entity"+ "ragflow/internal/parser/charset"+ "ragflow/internal/parser/media""ragflow/internal/parser/tableutil")type HTMLParser struct {RemoveHeaderFooter boolRemoveTOC bool+ textOnly bool}func NewHTMLParser() *HTMLParser {return &HTMLParser{}}+// NewHTMLTextParser extracts HTML text without caching inline images.+func NewHTMLTextParser() *HTMLParser {+ return &HTMLParser{textOnly: true}+}+func (p *HTMLParser) String() string {return "HTMLParser"}@@ -77,8 +87,18 @@ func (p *HTMLParser) ParseWithResult(ctx context.Context, filename string, datareturn ParseResult{Err: fmt.Errorf("html parse: %w", err)}}var items []map[string]any- state := &htmlWalkState{}+ state := &htmlWalkState{+ refOnly: true,+ ctx: ctx,+ mediaCache: media.CacheFromContext(ctx),+ }+ if p.textOnly {+ state.resolveImage = func(string) (string, bool) { return "", false }+ }walkHTMLBlocksWithState(doc, &items, state)+ if state.err != nil {+ return ParseResult{Err: state.err}+ }if err := ctx.Err(); err != nil {return ParseResult{Err: err}}@@ -103,7 +123,7 @@ func (p *HTMLParser) ParseWithResult(ctx context.Context, filename string, data// decodeHTMLToUTF8 converts non-UTF-8 HTML bytes to UTF-8 and reports the// encoding label used. It delegates to the shared DecodeToUTF8 helper.func decodeHTMLToUTF8(data []byte) ([]byte, string) {- return DecodeToUTF8(data, "text/html")+ return charset.DecodeToUTF8(data, "text/html")}type htmlWalkState struct {@@ -111,7 +131,14 @@ type htmlWalkState struct {mediaOrder intskippedInlineImages intmediaBudget *embeddedMediaBudget- resolveImage func(string) (string, bool)+ // refOnly defers image bytes to content-addressed references instead of+ // carrying the normalized data URI on the item. HTML sets it; formats+ // that still inline image bytes leave it false.+ refOnly bool+ ctx context.Context+ mediaCache media.Cache+ resolveImage func(string) (string, bool)+ err error}func (s *htmlWalkState) warnings() []string {@@ -122,30 +149,59 @@ func (s *htmlWalkState) warnings() []string {return warnings}-func (s *htmlWalkState) imageSource(src string) (string, bool) {+func (s *htmlWalkState) imageSource(src string) (string, *entity.MediaRef, bool) {+ if s.err != nil {+ return "", nil, false+ }if s.resolveImage != nil {- return s.resolveImage(src)+ normalized, ok := s.resolveImage(src)+ return normalized, nil, ok}- if !isHTMLDataImageSource(src) {- return "", false+ if !media.IsHTMLDataImageSource(src) {+ return "", nil, false+ }+ if s.refOnly {+ if media.HTMLImageExceedsLimit(src) {+ return "", nil, false+ }+ mime, data, ok := media.DecodeHTMLImageSource(src)+ if !ok {+ return "", nil, false+ }+ if s.mediaCache == nil {+ s.err = fmt.Errorf("html media cache is not configured")+ return "", nil, false+ }+ ref, err := s.mediaCache.Put(s.ctx, "html", mime, data)+ if err != nil {+ s.err = fmt.Errorf("html media cache write: %w", err)+ return "", nil, false+ }+ return "", &ref, true}if s.mediaBudget == nil {s.mediaBudget = newEmbeddedMediaBudget()}if !s.mediaBudget.reserveItem() {- return "", false+ return "", nil, false}- normalized, size, ok := normalizeHTMLImageSource(src)- if !ok || !s.mediaBudget.includeReservedSize(size) {- return "", false+ normalized, size, _, ok := media.NormalizeHTMLImageSource(src)+ if !ok {+ return "", nil, false}- return normalized, true+ if !s.mediaBudget.includeReservedSize(int(size)) {+ return "", nil, false+ }+ return normalized, nil, true}// walkHTMLBlocksWithState emits normalized text and image items in document// order. Inline formatting is collapsed into its parent text; script, style,// and noscript subtrees are skipped.func walkHTMLBlocksWithState(root *html.Node, out *[]map[string]any, state *htmlWalkState) {+ if state.err != nil {+ return+ }// Text and inline elements directly under <body> are one run of text, as// a browser lays them out, so they are collected into one item. Emitted// one item per text node and per inline element, "Hello <b>world</b>!"@@ -159,6 +215,9 @@ func walkHTMLBlocksWithState(root *html.Node, out *[]map[string]any, state *html}defer flushRun()for child := root.FirstChild; child != nil; child = child.NextSibling {+ if state.err != nil {+ return+ }// Invisible nodes neither show up nor end the run around them.if child.Type == html.CommentNode || (child.Type == html.ElementNode &&(child.Data == "script" || child.Data == "style" || child.Data == "noscript" || child.Data == "template")) {@@ -378,6 +437,9 @@ func flushLeafText(w *leafWriter, out *[]map[string]any, layout string, trim boo}func walkHTMLLeaf(n *html.Node, w *leafWriter, out *[]map[string]any, layout string, trim bool, state *htmlWalkState) {+ if state.err != nil {+ return+ }switch n.Type {case html.TextNode:w.writeText(n.Data)@@ -392,23 +454,26 @@ func walkHTMLLeaf(n *html.Node, w *leafWriter, out *[]map[string]any, layout str}if n.Data == "img" {src := htmlAttribute(n, "src")- normalized, ok := state.imageSource(src)+ normalized, ref, ok := state.imageSource(src)if !ok {if state.resolveImage != nil {w.writeText(htmlAttribute(n, "alt"))- } else if isHTMLDataImageSource(src) {+ } else if media.IsHTMLDataImageSource(src) {state.skippedInlineImages++}return}flushLeafText(w, out, layout, trim)- appendHTMLImageItem(out, state, normalized, htmlAttribute(n, "alt"), "", 0, 0)+ appendHTMLImageItem(out, state, normalized, ref, htmlAttribute(n, "alt"), "", 0, 0)return}if n.Data == "pre" || n.Data == "textarea" {// Verbatim: no folding, no injected block breaks.w.pre = truefor child := n.FirstChild; child != nil; child = child.NextSibling {+ if state.err != nil {+ return+ }walkHTMLLeaf(child, w, out, layout, trim, state)}w.pre = false@@ -435,6 +500,9 @@ func walkHTMLLeaf(n *html.Node, w *leafWriter, out *[]map[string]any, layout strw.hardBreak()}for child := n.FirstChild; child != nil; child = child.NextSibling {+ if state.err != nil {+ return+ }walkHTMLLeaf(child, w, out, layout, trim, state)}if !w.pre && isBlockTag(n.Data) && w.b.Len() > 0 && !w.endsNL {@@ -445,12 +513,16 @@ func walkHTMLLeaf(n *html.Node, w *leafWriter, out *[]map[string]any, layout strtype htmlTableImage struct {src string+ ref *entity.MediaRefalt stringrow intcolumn int}func emitHTMLTable(n *html.Node, out *[]map[string]any, state *htmlWalkState) {+ if state.err != nil {+ return+ }images, skippedInlineImages := htmlTableImages(n, state)state.skippedInlineImages += skippedInlineImagesmarkup := renderTableHTML(n)@@ -476,7 +548,7 @@ func emitHTMLTable(n *html.Node, out *[]map[string]any, state *htmlWalkState) {}*out = append(*out, table)for _, media := range images {- appendHTMLImageItem(out, state, media.src, media.alt, tableID, media.row, media.column)+ appendHTMLImageItem(out, state, media.src, media.ref, media.alt, tableID, media.row, media.column)}}@@ -487,6 +559,9 @@ func htmlTableImages(table *html.Node, state *htmlWalkState) ([]htmlTableImage,columnCounts := make(map[int]int)var walk func(node *html.Node, row, column int)walk = func(node *html.Node, row, column int) {+ if state.err != nil {+ return+ }if node.Type == html.ElementNode {switch node.Data {case "tr":@@ -498,18 +573,22 @@ func htmlTableImages(table *html.Node, state *htmlWalkState) ([]htmlTableImage,column = columnCounts[row]case "img":src := htmlAttribute(node, "src")- normalized, ok := state.imageSource(src)+ normalized, ref, ok := state.imageSource(src)if !ok {+ if state.err != nil {+ return+ }if state.resolveImage != nil {alt := htmlAttribute(node, "alt")node.Type, node.Data, node.Attr = html.TextNode, alt, nil- } else if isHTMLDataImageSource(src) {+ } else if media.IsHTMLDataImageSource(src) {skippedInlineImages++removeHTMLImageSource(node)}} else {images = append(images, htmlTableImage{src: normalized,+ ref: ref,alt: htmlAttribute(node, "alt"),row: row,column: column,@@ -522,6 +601,9 @@ func htmlTableImages(table *html.Node, state *htmlWalkState) ([]htmlTableImage,}}for child := node.FirstChild; child != nil; child = child.NextSibling {+ if state.err != nil {+ return+ }walk(child, row, column)}}@@ -539,14 +621,19 @@ func removeHTMLImageSource(n *html.Node) {n.Attr = attrs}-func appendHTMLImageItem(out *[]map[string]any, state *htmlWalkState, src, alt, parentTableID string, row, column int) {+func appendHTMLImageItem(out *[]map[string]any, state *htmlWalkState, src string, ref *entity.MediaRef, alt, parentTableID string, row, column int) {state.mediaOrder++item := map[string]any{"text": strings.TrimSpace(alt),"doc_type_kwd": "image","media_order": state.mediaOrder,}- item["image"] = src+ if !state.refOnly {+ item["image"] = src+ }+ if state.refOnly && ref != nil {+ item["media_ref"] = ref+ }if parentTableID != "" {item["parent_table_id"] = parentTableIDitem["row_index"] = row@@ -555,28 +642,6 @@ func appendHTMLImageItem(out *[]map[string]any, state *htmlWalkState, src, alt,*out = append(*out, item)}-func normalizeHTMLImageSource(src string) (string, int, bool) {- src = strings.TrimSpace(src)- if !isHTMLDataImageSource(src) {- return "", 0, false- }- separator := strings.IndexByte(src, ',')- if separator <= len("data:image/") || separator > 128 || !strings.EqualFold(src[separator-len(";base64"):separator], ";base64") {- return "", 0, false- }- payload, size, ok := normalizeBase64ImagePayload(src[separator+1:], maxEmbeddedImageBytes)- if !ok {- return "", 0, false- }- return strings.ToLower(src[:separator+1]) + payload, int(size), true-}--func isHTMLDataImageSource(src string) bool {- const dataPrefix = "data:image/"- src = strings.TrimSpace(src)- return len(src) >= len(dataPrefix) && strings.EqualFold(src[:len(dataPrefix)], dataPrefix)-}-func htmlAttribute(n *html.Node, key string) string {for _, attr := range n.Attr {if strings.EqualFold(attr.Key, key) {diff --git a/internal/parser/parser/image_media.go b/internal/parser/parser/image_media.goindex 90fb9e4528..eff07611a8 100644--- a/internal/parser/parser/image_media.go+++ b/internal/parser/parser/image_media.go@@ -27,11 +27,6 @@ import (deepdocpdf "ragflow/internal/deepdoc/parser/pdf")-const (- // MaxImagePayloadBytes bounds compressed image data accepted by media paths.- MaxImagePayloadBytes = 32 << 20-)-// EnvImageRasterMaxBytes names the environment variable that sets the// decoded-raster byte ceiling for image parsing (media dispatch and inline// vision images). It mirrors Python's picture.py, which imposes no image sizediff --git a/internal/parser/parser/image_payload.go b/internal/parser/parser/image_payload.godeleted file mode 100644index 478d11d24d..0000000000--- a/internal/parser/parser/image_payload.go+++ /dev/null@@ -1,89 +0,0 @@-//-// 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.-//--package parser--import (- "encoding/base64"- "io"- "strings"-)--// normalizeBase64ImagePayload validates an external image payload within its-// decoded byte limit and returns standard base64 with padding, no CR/LF, and-// the decoded byte count. Validation streams into io.Discard instead of-// allocating decoded image buffers.-func normalizeBase64ImagePayload(payload string, maxDecodedBytes int) (string, int64, bool) {- if maxDecodedBytes < 0 {- return "", 0, false- }- encodedBytes, ok := scanBase64ImagePayload(payload, base64.StdEncoding.EncodedLen(maxDecodedBytes))- if !ok {- return "", 0, false- }- payload = strings.ReplaceAll(payload, "\r", "")- payload = strings.ReplaceAll(payload, "\n", "")- if remainder := encodedBytes % 4; remainder != 0 {- payload += strings.Repeat("=", 4-remainder)- }- decoder := base64.NewDecoder(base64.StdEncoding, strings.NewReader(payload))- decodedBytes, err := io.CopyN(io.Discard, decoder, int64(maxDecodedBytes)+1)- if err != io.EOF || decodedBytes == 0 || decodedBytes > int64(maxDecodedBytes) {- return "", 0, false- }- return payload, decodedBytes, true-}--// scanBase64ImagePayload counts the base64 characters of an image payload-// (CR/LF excluded) and rejects a payload whose padding is malformed: '=' may-// only appear in the final quantum, at most twice, and the character count-// must form whole quanta.-//-// The padding rule is what rejects data that follows a padded quantum. Go's-// streaming decoder only reports that when the whole payload lands in one-// decode call, so it cannot be left to the decoder.-func scanBase64ImagePayload(payload string, maxEncodedBytes int) (int, bool) {- encodedBytes := 0- padding := 0- sawPadding := false- for i := 0; i < len(payload); i++ {- if payload[i] == '\r' || payload[i] == '\n' {- continue- }- encodedBytes++- if encodedBytes > maxEncodedBytes {- return 0, false- }- if payload[i] == '=' {- sawPadding = true- padding++- if padding > 2 {- return 0, false- }- continue- }- if sawPadding {- return 0, false- }- }- if encodedBytes == 0 {- return 0, false- }- if encodedBytes%4 == 1 || (padding > 0 && encodedBytes%4 != 0) {- return 0, false- }- return encodedBytes, true-}diff --git a/internal/parser/parser/image_payload_test.go b/internal/parser/parser/image_payload_test.goindex 9c6f5d84f1..77f38d3300 100644--- a/internal/parser/parser/image_payload_test.go+++ b/internal/parser/parser/image_payload_test.go@@ -2,8 +2,10 @@ package parserimport ("context"- "strings"+ "encoding/base64""testing"++ "ragflow/internal/entity")func TestParsersNormalizeInlineImagePayload(t *testing.T) {@@ -31,12 +33,16 @@ func TestParsersNormalizeInlineImagePayload(t *testing.T) {for _, format := range []string{"html", "html_table", "markdown"} {t.Run(tc.name+"/"+format, func(t *testing.T) {uri := "data:image/png;base64," + tc.payload+ var source []bytevar result ParseResult+ ctx, cache := recordingMediaContext()switch format {case "html":- result = NewHTMLParser().ParseWithResult(context.Background(), "image.html", []byte(`<p><img alt="caption" src="`+uri+`"></p>`))+ source = []byte(`<p><img alt="caption" src="` + uri + `"></p>`)+ result = NewHTMLParser().ParseWithResult(ctx, "image.html", source)case "html_table":- result = NewHTMLParser().ParseWithResult(context.Background(), "image.html", []byte(`<table><tr><td><img alt="caption" src="`+uri+`"></td></tr></table>`))+ source = []byte(`<table><tr><td><img alt="caption" src="` + uri + `"></td></tr></table>`)+ result = NewHTMLParser().ParseWithResult(ctx, "image.html", source)case "markdown":result = markdown.ParseWithResult(context.Background(), "image.md", []byte(""))}@@ -45,14 +51,25 @@ func TestParsersNormalizeInlineImagePayload(t *testing.T) {}images := 0for _, item := range result.JSON {- image, _ := item.ToMap()["image"].(string)+ m := item.ToMap()+ var image string+ if format == "markdown" {+ image, _ = m["image"].(string)+ } else {+ ref := entity.MediaRefFromAny(m["media_ref"])+ if ref == nil {+ continue+ }+ data, err := cache.Get(ctx, *ref)+ if err != nil {+ t.Fatalf("resolve: %v", err)+ }+ image = base64.StdEncoding.EncodeToString(data)+ }if image == "" {continue}images++- if format != "markdown" {- image = strings.TrimPrefix(image, "data:image/png;base64,")- }if image != tc.want {t.Errorf("image payload = %q, want %q", image, tc.want)}@@ -71,31 +88,3 @@ func TestParsersNormalizeInlineImagePayload(t *testing.T) {}}}--func TestNormalizeBase64ImagePayloadByteLimit(t *testing.T) {- for _, tc := range []struct {- name, payload string- limit int- want string- wantSize int64- }{- {"negative_limit", "YQ", -1, "", 0},- {"zero_limit", "YQ", 0, "", 0},- {"exact_limit_padded", "YWI=", 2, "YWI=", 2},- {"exact_limit_unpadded", "YWI", 2, "YWI=", 2},- {"exact_limit_wrapped", "YW\r\nI", 2, "YWI=", 2},- {"over_limit_padded", "YWI=", 1, "", 0},- {"over_limit_unpadded", "YWI", 1, "", 0},- {"over_encoded_limit", "YWJjZA==", 2, "", 0},- {"data_after_padding", "G0==JbjQ", 16, "", 0},- {"data_after_padding_long", "aMRFPqfZALtY6rw50P==Pn5d", 16, "", 0},- } {- t.Run(tc.name, func(t *testing.T) {- got, size, ok := normalizeBase64ImagePayload(tc.payload, tc.limit)- if got != tc.want || ok != (tc.want != "") || size != tc.wantSize {- t.Errorf("normalizeBase64ImagePayload(%q, %d) = (%q, %d, %v), want (%q, %d, %v)",- tc.payload, tc.limit, got, size, ok, tc.want, tc.wantSize, tc.want != "")- }- })- }-}diff --git a/internal/parser/parser/json_parser.go b/internal/parser/parser/json_parser.goindex 07b8491ba8..fcb2eb9623 100644--- a/internal/parser/parser/json_parser.go+++ b/internal/parser/parser/json_parser.go@@ -38,6 +38,8 @@ import ("fmt""io""strings"++ "ragflow/internal/parser/charset")// JSONParser handles JSON / JSONL / LDJSON files.@@ -55,7 +57,7 @@ func (p *JSONParser) String() string {// shape (array, single object, or line-delimited) and emits one JSON// item per logical record, with {text, doc_type_kwd:"text"}.func (p *JSONParser) ParseWithResult(ctx context.Context, filename string, data []byte) ParseResult {- decoded, encName := DecodeToUTF8(data, "application/json")+ decoded, encName := charset.DecodeToUTF8(data, "application/json")text := string(bytes.TrimSpace(decoded))if text == "" {return ParseResult{diff --git a/internal/parser/parser/markdown_parser.go b/internal/parser/parser/markdown_parser.goindex 71d0cdadb9..466737f3d3 100644--- a/internal/parser/parser/markdown_parser.go+++ b/internal/parser/parser/markdown_parser.go@@ -34,6 +34,9 @@ import (mdhtml "github.com/gomarkdown/markdown/html"mdparser "github.com/gomarkdown/markdown/parser""golang.org/x/net/html"++ "ragflow/internal/parser/charset"+ "ragflow/internal/parser/media")// dataURIPrefix is the MIME prefix for data URI images.@@ -102,7 +105,7 @@ func (p *MarkdownParser) ParseWithResult(ctx context.Context, filename string, d// parseWithState keeps media identity and budget across fragments of one document.// Its warnings describe this fragment; the caller adds state.warnings once.func (p *MarkdownParser) parseWithState(ctx context.Context, filename string, data []byte, state *htmlWalkState) ParseResult {- decoded, _ := DecodeToUTF8(data, "text/markdown")+ decoded, _ := charset.DecodeToUTF8(data, "text/markdown")// The final blank line also terminates a raw HTML block at EOF.rawText := string(decoded) + "\n\n"blockParser := markdownNew()@@ -643,7 +646,7 @@ func resolveImageURL(ctx context.Context, imageURL string, budget *embeddedMediareturn "", nil, false, false}var decodedSize int64- encoded, decodedSize, resolved = normalizeBase64ImagePayload(imageURL[idx+len("base64,"):], MaxImagePayloadBytes)+ encoded, decodedSize, _, resolved = media.NormalizeBase64ImagePayload(imageURL[idx+len("base64,"):], media.MaxImagePayloadBytes)if !resolved {return "", nil, false, false}@@ -743,12 +746,12 @@ func fetchImage(ctx context.Context, rawURL string) ([]byte, error) {if resp.StatusCode < 200 || resp.StatusCode >= 300 {return nil, fmt.Errorf("markdown: fetch image %s: HTTP %d", rawURL, resp.StatusCode)}- body, err := io.ReadAll(io.LimitReader(resp.Body, MaxImagePayloadBytes+1))+ body, err := io.ReadAll(io.LimitReader(resp.Body, media.MaxImagePayloadBytes+1))if err != nil {return nil, fmt.Errorf("markdown: read image %s: %w", rawURL, err)}- if len(body) > MaxImagePayloadBytes {- return nil, fmt.Errorf("markdown: image %s exceeds %d-byte limit", rawURL, MaxImagePayloadBytes)+ if len(body) > media.MaxImagePayloadBytes {+ return nil, fmt.Errorf("markdown: image %s exceeds %d-byte limit", rawURL, media.MaxImagePayloadBytes)}if len(body) == 0 {return nil, fmt.Errorf("markdown: image %s is empty", rawURL)diff --git a/internal/parser/parser/media_budget.go b/internal/parser/parser/media_budget.goindex 5e25ea1af3..acdd7767b9 100644--- a/internal/parser/parser/media_budget.go+++ b/internal/parser/parser/media_budget.go@@ -18,10 +18,12 @@ package parserimport ("fmt"++ "ragflow/internal/parser/media")const (- maxEmbeddedImageBytes = MaxImagePayloadBytes+ maxEmbeddedImageBytes = media.MaxImagePayloadBytesmaxEmbeddedDocumentImageBytes = 64 << 20maxEmbeddedMediaItems = 256)diff --git a/internal/parser/parser/picture_parser.go b/internal/parser/parser/picture_parser.goindex 162613cf13..5481c2bd70 100644--- a/internal/parser/parser/picture_parser.go+++ b/internal/parser/parser/picture_parser.go@@ -25,6 +25,8 @@ import ("fmt""path/filepath""strings"++ "ragflow/internal/parser/media")// imageExtensions mirrors Python's visual extensions used in@@ -69,8 +71,8 @@ func (p *PictureParser) ParseWithResult(ctx context.Context, filename string, daErr: fmt.Errorf("picture: unsupported extension %q (filename: %s); accepted: .jpg/.jpeg/.png/.gif/.bmp/.tiff/.tif/.webp/.svg/.ico/.avif/.heic/...", ext, filename),}}- if len(data) == 0 || len(data) > MaxImagePayloadBytes {- return ParseResult{Err: fmt.Errorf("picture: image payload size %d is outside the %d-byte limit", len(data), MaxImagePayloadBytes)}+ if len(data) == 0 || len(data) > media.MaxImagePayloadBytes {+ return ParseResult{Err: fmt.Errorf("picture: image payload size %d is outside the %d-byte limit", len(data), media.MaxImagePayloadBytes)}}release, err := AcquireImageMedia(ctx)diff --git a/internal/parser/parser/text_parser.go b/internal/parser/parser/text_parser.goindex 4cca42cc6e..1fa7cbffcb 100644--- a/internal/parser/parser/text_parser.go+++ b/internal/parser/parser/text_parser.go@@ -30,6 +30,8 @@ package parserimport ("context""strings"++ "ragflow/internal/parser/charset")// TextParser is the text&code family parser. It implements the@@ -45,7 +47,7 @@ func NewTextParser() *TextParser {// output format is "json" to mirror the parser component boundary. No fixed// delimiter or token budget is applied here.func (p *TextParser) ParseWithResult(ctx context.Context, filename string, data []byte) ParseResult {- decoded, encName := DecodeToUTF8(data, "text/plain")+ decoded, encName := charset.DecodeToUTF8(data, "text/plain")return ParseResult{File: map[string]any{"name": filename,diff --git a/internal/server/ingestor/server.go b/internal/server/ingestor/server.goindex 1e1e0cbad1..cb974cea37 100644--- a/internal/server/ingestor/server.go+++ b/internal/server/ingestor/server.go@@ -104,7 +104,7 @@ func Run(ctx context.Context, cancel context.CancelFunc, serverName string, argsKV: kvrocks.Get(),}// Fail fast at the assembly point: a misconfigured ingestor (missing doc- // engine, database, or message queue) must never reach Start as a "healthy"+ // engine, database, message queue, or Kvrocks) must never reach Start as a "healthy"// service that silently cannot consume.if err = ingestorDeps.Validate(); err != nil {common.Error("Invalid ingestor dependencies", err)diff --git a/internal/service/file/file_content.go b/internal/service/file/file_content.goindex 37bb7ebdcc..3ac53756c1 100644--- a/internal/service/file/file_content.go+++ b/internal/service/file/file_content.go@@ -221,6 +221,9 @@ func parseAgentUploadContent(ctx context.Context, filename string, data []byte,if err != nil {return "", err}+ if fileType == utility.FileTypeHTML {+ fp = parser.NewHTMLTextParser()+ }if configurable, ok := fp.(interface{ ConfigureFromSetup(map[string]any) }); ok {configurable.ConfigureFromSetup(map[string]any{"layout_recognize": layoutRecognize})}@@ -273,6 +276,9 @@ func parseFileContent(ctx context.Context, filename string, data []byte) stringif err != nil {return string(data)}+ if fileType == utility.FileTypeHTML {+ fp = parser.NewHTMLTextParser()+ }res := fp.ParseWithResult(ctx, filename, data)if res.Err != nil {return string(data)diff --git a/internal/service/file/file_content_test.go b/internal/service/file/file_content_test.goindex b445eabd8a..0e72449ae0 100644--- a/internal/service/file/file_content_test.go+++ b/internal/service/file/file_content_test.go@@ -143,3 +143,26 @@ func TestParseFileContent_MarkdownOutputFormat(t *testing.T) {t.Skip("markdown parser returned empty (integration-only)")}}++func TestHTMLContentExtractionWithoutMediaCache(t *testing.T) {+ input := []byte(`<p>before</p><img alt="figure" src="data:image/png;base64,aGVsbG8="><p>after</p>`)+ for name, parse := range map[string]func() (string, error){+ "file": func() (string, error) { return parseFileContent(t.Context(), "sample.html", input), nil },+ "agent": func() (string, error) { return parseAgentUploadContent(t.Context(), "sample.html", input, "") },+ } {+ t.Run(name, func(t *testing.T) {+ got, err := parse()+ if err != nil {+ t.Fatal(err)+ }+ for _, want := range []string{"before", "figure", "after"} {+ if !strings.Contains(got, want) {+ t.Errorf("missing %q: %q", want, got)+ }+ }+ if strings.Contains(got, "base64,") || strings.Contains(got, "<img") {+ t.Fatalf("raw HTML leaked: %q", got)+ }+ })+ }+}