Skip to content

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

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.go
index 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) (Response
if 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.go
index 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.md
index 808182e422..3b784556e9 100644
--- a/internal/development.md
+++ b/internal/development.md
@@ -307,6 +307,10 @@ export KVROCKS_PORT=6379
In docker the Go services override these to `kvrocks:6379` automatically
(see `docker-compose-go.yml`). If Kvrocks is unreachable at startup the
process 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 RAGFlow
diff --git a/internal/engine/kvrocks/redis_test.go b/internal/engine/kvrocks/redis_test.go
index 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.go
new file mode 100644
index 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.go
index 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.go
index 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.go
index 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 *ti
if 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.go
index 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 chunker
import (
@@ -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.go
index 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 + "-" + chunkID
if 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.go
new file mode 100644
index 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&#9;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.go
index 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 []string
var img string
+ var mediaRef *entity.MediaRef
for _, 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 = mediaRef
return chunkOutputs([]schema.ChunkDoc{out})
}
diff --git a/internal/ingestion/component/chunker/one_test.go b/internal/ingestion/component/chunker/one_test.go
index 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.go
index 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) (m
if pair.RowNum >= 0 {
chunk.TopInt = []int{pair.RowNum}
}
- if pair.Image != "" {
+ if pair.Image != "" || pair.MediaRef != nil {
chunk.Image = pair.Image
+ chunk.MediaRef = pair.MediaRef
chunk.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.MediaRef
PDFPositions json.RawMessage
Positions json.RawMessage
Sheet string
@@ -443,6 +447,7 @@ func extractQAJSON(items []schema.ChunkDoc, fileType string) []qaPair {
p.Sheet = item.Sheet
p.SheetIndex = item.SheetIndex
p.Image = item.Image
+ p.MediaRef = item.MediaRef
p.PDFPositions = item.PDFPositions
if len(p.Positions) == 0 {
p.Positions = item.Positions
diff --git a/internal/ingestion/component/chunker/register.go b/internal/ingestion/component/chunker/register.go
index 0f5489d065..59c9e7a230 100644
--- a/internal/ingestion/component/chunker/register.go
+++ b/internal/ingestion/component/chunker/register.go
@@ -27,9 +27,12 @@ package chunker
import (
"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 m
if 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 m
if 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, nil
diff --git a/internal/ingestion/component/chunker/title.go b/internal/ingestion/component/chunker/title.go
index 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 string
imgID *string
image string
+ mediaRef *entity.MediaRef
layout string
pdfPositions json.RawMessage
positions json.RawMessage
diff --git a/internal/ingestion/component/chunker/title_structured_media_test.go b/internal/ingestion/component/chunker/title_structured_media_test.go
index 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.go
index 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.ChunkerFromUpstrea
if 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.go
index 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 than
diff --git a/internal/ingestion/component/media_materialize.go b/internal/ingestion/component/media_materialize.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
index 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 never
diff --git a/internal/ingestion/component/schema/chunk_media_ref_test.go b/internal/ingestion/component/schema/chunk_media_ref_test.go
new file mode 100644
index 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.go
index ad631378a4..30354dc24e 100644
--- a/internal/ingestion/component/schema/chunk_types.go
+++ b/internal/ingestion/component/schema/chunk_types.go
@@ -18,6 +18,8 @@ package schema
import (
"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.go
index 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])] = value
diff --git a/internal/ingestion/component/vision_config_test.go b/internal/ingestion/component/vision_config_test.go
index 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.go
index 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 := false
descriptions := make([]string, len(items))
failures := make([]string, len(items))
+ mediaFailures := make([]error, len(items))
var wg sync.WaitGroup
sem := make(chan struct{}, visionEnhancementConcurrency)
var settled atomic.Int64
@@ -306,7 +313,9 @@ func maybeDispatchVisionEnhancement(
}
var resource *visionImage
func() {
- 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 := 0
firstFailure := ""
diff --git a/internal/ingestion/component/vision_enhancement_test.go b/internal/ingestion/component/vision_enhancement_test.go
index 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.go
index 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.MaxImagePayloadBytes
maxVLMEncodedBytes = (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 a
diff --git a/internal/ingestion/deps.go b/internal/ingestion/deps.go
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
index 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.go
new file mode 100644
index 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.go
index 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.Canvas
tracker *canvas.RunTracker // optional injected; nil -> resolve at Run
kv *kvrocks.Client // optional; nil -> no tracker fallback (unit/test runs)
+ media media.Cache // optional injected run media cache
factory runtime.ComponentFactory // optional instance-scoped component factory
sink 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.go
index 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 = true
m.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.go
index 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.go
index 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.go
index 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.go
similarity index 97%
rename from internal/parser/parser/charset.go
rename to internal/parser/charset/charset.go
index 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.go
similarity index 70%
rename from internal/parser/parser/charset_test.go
rename to internal/parser/charset/charset_test.go
index 23c1c0988b..9c2227d6f9 100644
--- a/internal/parser/parser/charset_test.go
+++ b/internal/parser/charset/charset_test.go
@@ -1,9 +1,6 @@
-package parser
+package charset
import (
- "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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
index 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.go
index 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.go
index 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 string
Image string
+ Media *entity.MediaRef
Sheet string
Positions Positions
Extra 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.go
index 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[s
if 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.go
index 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{
+ "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.go
index 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.go
index 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.go
index 9950e39551..c728c0a082 100644
--- a/internal/parser/parser/html_media_test.go
+++ b/internal/parser/parser/html_media_test.go
@@ -2,16 +2,116 @@ package parser
import (
"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 := 0
for _, 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&#47;png;base64,aGVsbG8=">`,
+ "entity comma": `<img src="data:image/png;base64&#44;aGVsbG8=">`,
+ "semicolonless entity": `<img src="data:image/png;base64,aGVsbG8&#43">`,
+ "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.go
index 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 bool
RemoveTOC 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, data
return 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 int
skippedInlineImages int
mediaBudget *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 = true
for 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 str
w.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 str
type htmlTableImage struct {
src string
+ ref *entity.MediaRef
alt string
row int
column int
}
func emitHTMLTable(n *html.Node, out *[]map[string]any, state *htmlWalkState) {
+ if state.err != nil {
+ return
+ }
images, skippedInlineImages := htmlTableImages(n, state)
state.skippedInlineImages += skippedInlineImages
markup := 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"] = parentTableID
item["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.go
index 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 size
diff --git a/internal/parser/parser/image_payload.go b/internal/parser/parser/image_payload.go
deleted file mode 100644
index 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.go
index 9c6f5d84f1..77f38d3300 100644
--- a/internal/parser/parser/image_payload_test.go
+++ b/internal/parser/parser/image_payload_test.go
@@ -2,8 +2,10 @@ package parser
import (
"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 []byte
var 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("![caption](<"+uri+">)"))
}
@@ -45,14 +51,25 @@ func TestParsersNormalizeInlineImagePayload(t *testing.T) {
}
images := 0
for _, 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.go
index 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.go
index 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 *embeddedMedia
return "", 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.go
index 5e25ea1af3..acdd7767b9 100644
--- a/internal/parser/parser/media_budget.go
+++ b/internal/parser/parser/media_budget.go
@@ -18,10 +18,12 @@ package parser
import (
"fmt"
+
+ "ragflow/internal/parser/media"
)
const (
- maxEmbeddedImageBytes = MaxImagePayloadBytes
+ maxEmbeddedImageBytes = media.MaxImagePayloadBytes
maxEmbeddedDocumentImageBytes = 64 << 20
maxEmbeddedMediaItems = 256
)
diff --git a/internal/parser/parser/picture_parser.go b/internal/parser/parser/picture_parser.go
index 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, da
Err: 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.go
index 4cca42cc6e..1fa7cbffcb 100644
--- a/internal/parser/parser/text_parser.go
+++ b/internal/parser/parser/text_parser.go
@@ -30,6 +30,8 @@ package parser
import (
"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.go
index 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, args
KV: 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.go
index 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) string
if 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.go
index 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)
+ }
+ })
+ }
+}