* feat(agent): let the WeKnora assistant read the bundled documentation
Embeds the website-docs pages (01-07) into the server and adds
search_weknora_docs / read_weknora_doc for the built-in assistant, so it
answers how WeKnora works from the docs of the running version.
- pages split into sections with the site's VitePress anchors; Mermaid
dropped, screenshots reduced to captions, links rewritten to public URLs
- in-memory BM25 over sections, with Han character pairs and whole
identifiers such as OLLAMA_BASE_URL or v0.8.3
- granted to the built-in assistant by ID, like the operation tools; the
docs are public, so no signed-in user is required
- tests check every embedded page parses and every internal link resolves
* fix(agent): read long doc sections to the end and keep docs on a broken page
- read_weknora_doc takes an offset: a section too long for one read is cut
at a line break and returns next_offset, so leaf sections such as the
model field reference are readable to the end instead of losing the tail.
- Reads follow the registry's output budget (capped at 8000 runes).
- Percent-encoded anchors, as a browser copies them, and http:// doc URLs
resolve.
- productdocs.Load leaves out a page it cannot parse and reports it, so one
broken page no longer withholds the documentation tools.
- App CI runs on changes to the embedded doc pages and the sidebar config,
where the parse and link tests now apply.
* feat(agent): add the built-in WeKnora assistant with an operation catalog
Adds builtin-weknora-assistant, which inspects and manages WeKnora with the
signed-in user's permissions:
- find_operations / run_operation over an allow-listed API operation catalog,
dispatched in-process through the real router as the user
- builtin approval for write/destructive operations, refused when
non-interactive
- agent attribution in knowledge base activity, including async tasks
- page_context request field, narrowed to the turn's search targets and
rendered into runtime_context with model handles
* refactor(agent): compile the operation catalog from x-agent Swagger annotations
The catalog was a hand-written copy of what the swag annotations already
describe: routes, parameters, enums and response shapes. It now compiles
from the Swagger document embedded in the binary. Handlers opt in with
// @x-agent {"id":"knowledge.delete","risk":"destructive",...}
// @x-agent-hint "Cannot be undone."
// @Param id path string true "知识ID" extensions(x-agent=knowledge_id)
and response types mark the fields the model may see with an
extensions:"x-agent" struct tag. Exposure stays opt-in at every level:
unmarked operations, parameters and fields are not reachable, so a new
field on Knowledge or a new query parameter never reaches the model by
accident. NewCatalog still enforces the safety rules (forbidden areas,
risk versus method, approval targets), and a test fails when the
annotations and docs/swagger.json disagree.
The twelve operations compile to the same routes, parameters and
results as before; document results now share one field set, and the
parse_status filter accepts deleting, which the API supports.
* fix(agent): enforce resume and wiki context scopes
* feat(agent): persist human-in-the-loop prompts with a shared broker
Tool approvals and MCP OAuth prompts are now rows in agent_prompts,
awaited through hitl.Broker (lease, DB polling, Redis wake-up, per-kind
answer validation). Resolve is bound to session and kind. This is P1 of
the suspend/resume design; runs still block as before.
* feat(agent): suspend runs whose prompt outlives a short in-memory wait
Behind agent.prompt_suspend_enabled (off by default). A run raised from the
HTTP stream saves its state when a tool approval is raised; after the hot
wait the prompt moves to suspended and the assistant message is saved as
awaiting_input instead of blocking. A reaper takes over prompts whose
waiting replica stopped renewing its lease. Resume comes in a later change.
* feat(agent): resume suspended runs once their prompt is answered
The replica that records the answer resumes the run in process under the
prompt's lease. Superseded, expired and abandoned runs are closed with a
result for every tool call, and approved tools are never replayed.
* feat(agent): let users answer suspended tool approvals and follow the resumed run
* feat(agent): ask_user tool and generic prompt answer endpoint
- ask_user built-in tool: options, short forms or free text; validated
answers, decline, suspend/resume like tool approval; non-interactive
callers (IM, API keys) are told to ask in the reply instead
- POST /agent/prompts/{prompt_id} (and embed variant) answers ask_user
and tool_approval prompts, returns resumed; SDK ResolveAgentPrompt
- agent_prompt_required/resolved events; AskUserCard sharing the
countdown with ToolApprovalCard; answered questions rebuilt as cards
from history
- awaiting-input messages keep their steps expanded so the pending card
stays visible; prompt cards keyed by their own id
- i18n for all locales; design doc updated
* fix(agent): keep prompt answers that race a suspending or vanished owner
- Resolve suspends a pending prompt whose owner's lease lapsed, as the
reaper would, so the answer resumes the run instead of waking nobody.
- Resuming waits for the suspending run to persist its message and clear
its live-run marker; a marker left by a vanished owner is cleared.
- A resumed run that suspends again on a new prompt no longer has its
message closed from the old state.
- tool_approval answers are decoded strictly and require "approved";
fix the SDK doc that showed {"decision": "approve"}.
- API-key runs block instead of suspending, since they cannot answer.
- A run state that cannot be saved falls back to an in-memory wait, and
NUL escapes are stripped from snapshots for jsonb.
* style(chat): align the ask_user card with the other interaction cards
Question and answer use the timeline's step text styles instead of
primary-colored and monospace text; options and form controls use the
compact step size, the number input spans the row, and the free-text
character counter is hidden.
* feat(chat): dock pending agent prompts above the composer
Tool approvals, ask_user questions and MCP OAuth prompts were answered
inline in the agent timeline, where a long answer or scrolling back
pushes them out of view. Open prompts of a streaming or suspended run
now gather in a dock above the composer (main chat and embed), one at a
time with a pager, lettered options and Enter to submit. The timeline
keeps a one-line record with a link back to the dock and the outcome
once answered. Views without a dock still answer inline.
* fix(agent): fence prompt ownership and preserve resumed turn context
* fix(agent): keep runs through consume errors and file prompts under the caller
Consume reported a store error as a lost claim, so an answer consumed
during a database hiccup detached its run: the message was never
persisted, the live-run marker stayed, and the reaper skipped the row
because the waiter had already dropped the snapshot. Consume now retries,
then decides from the row, and gives a run up only when the prompt is
known to have moved on.
Tool approvals and OAuth prompts of a shared agent were filed under the
agent's workspace, so the user's answer failed the tenant check and the
prompt timed out. Like ask_user, they now use the caller's workspace;
policy and token lookups stay in the agent's.
Enter on a picked option submits it instead of toggling it off, and
resume errors no longer report a nil cause.
* fix(agent): validate prompt choices and require durable approval claims
Reject malformed serialized option lists so the model can retry with valid arguments. Distinguish prompt consumption failures from lost ownership without authorizing side effects, and preserve native Enter selection for unselected choices.
* fix(agent): resolve prompt workflow lint errors
* fix(skill): do not fail installs on non-blocking observations
A working skill was rejected when the installer recorded a docs mismatch
as a blocker. Keep real setup failures in blockers and surface harmless
observations as notes.
* style(skill): wrap the install-report validation error
* feat(frontend): compact skill cards and install progress
Show each sandbox install on the card and collapse installer prompts, so
the skills page stays readable when a skill is installed in more than one place.
* fix(chat): include shared KBs in starter questions and stop composer jitter
Agents using all knowledge bases now draw starters from KBs shared into
the tenant, matching chat retrieval. The new-chat page skips refetches
whose scope did not change and only shows the skeleton on first load.
* fix(mcp): keep OAuth token expiry independent of the process time zone
mcp_oauth_tokens.expires_at is a naive TIMESTAMP column. The token store
computes the expiry from the process clock, the column drops its offset,
and the driver reads the stored wall clock back as UTC. When the
application runs outside UTC, every stored expiry is therefore shifted
by the process offset: with TZ=Asia/Shanghai, the docker compose default,
a token is reported as expiring eight hours after it really does.
WeKnora trusts that value. The OAuth status endpoint reports a token as
authorized for those extra hours, and the runtime neither refreshes it
ahead of time nor asks for authorization again. It sends the expired
access token to the MCP server and only recovers after the server
rejects it.
Promote the token and client timestamps to TIMESTAMP WITH TIME ZONE, as
migration 000072 did for API keys and resource grants, and normalize the
values the repository writes to UTC, so new rows are right even before
the migration is applied. The status endpoint keeps reporting the expiry
in UTC as before: the driver returns timestamptz values in the process
time zone, and the response would otherwise vary by deployment.
The migration cannot repair existing rows, because the time zone of the
process that wrote them is unknown. Like 000072, it reads them as UTC,
so they keep their shifted value until the token is authorized or
refreshed again.
* fix(migrations): renumber MCP OAuth timestamptz migration to 000118
000117 is now taken on main by messages_attachment_lookup.
---------
Co-authored-by: wizardchen <wizardchen@tencent.com>
The knowledge base description call hardcoded MaxTokens=800, sized for a
short JSON reply. Reasoning-style models can spend that budget on thinking
even when thinking is disabled, returning an empty completion that fails
generation with 'no gist' (issue #4221), and deployments had no way to
raise it.
Raise the default to 2048 and let operators override it with the
KNOWLEDGE_BASE_PROFILE_MAX_TOKENS environment variable (invalid or
non-positive values fall back to the default). Documented in .env.example.
Co-authored-by: LuckVd <LuckVd@users.noreply.github.com>
WeKnora runs behind other applications: they sign their users in and
call WeKnora with a tenant API key and X-External-User-ID, and WeKnora
keeps sessions and MCP OAuth tokens per external user. When an agent
uses an OAuth-protected MCP service, the only way to get that user's
token is the browser authorization code flow, and in this deployment
the user never sees WeKnora, so there is no browser to complete it.
Independently, an OAuth MCP service can only get its client through
dynamic client registration (RFC 7591), so authorization servers
without a registration endpoint cannot be used at all ("server does not
support dynamic client registration"), and servers that allow a grant
only to clients an administrator registered refuse a dynamic one.
JWT bearer grant. The application in front already knows who the user
is. POST /api/v1/mcp-services/:id/oauth/assertion lets it present a
signed assertion of that identity, such as the Identity Assertion JWT
Authorization Grant (ID-JAG) used by MCP's Enterprise-Managed
Authorization extension. WeKnora sends it to the service's
authorization server with the JWT bearer grant (RFC 7523) and stores
the token exactly like the callback does, so status, revoke, runtime
connections and, when the response carries a refresh token, refresh
use it unchanged. The assertion is forwarded unread; validating it is
up to the authorization server. The request reuses the principal from
authorize-url, the SSRF-safe HTTP client and the callback's connection
recycling, and the client the service already has. It does not run
dynamic client registration, which describes a redirect-based client;
without a client it answers 400. The token request outlives the caller,
so a token issued for an assertion that can only be used once is not
lost. A 4xx response other than 408 and 429, or a 2xx response carrying
an OAuth error, answers 400 with the OAuth error code and is logged; a
5xx, 408 or 429 response or a network failure answers 500. Request
logging masks the assertion field.
Pre-registered client. auth_config.client_id names a client registered
with the authorization server in advance, and client_secret is its
secret for a confidential client. When client_id is set it takes the
place of dynamic registration everywhere a client is read: the
authorization URL, the code exchange, the assertion grant and runtime
connections with their token refreshes. The values live on the service
rather than in mcp_oauth_clients, because a refresh rejected with
invalid_client deletes that row so the next authorization registers
again; an administrator's client would silently disappear. client_id is
non-secret: it is set through the main PUT, where an empty value clears
it, and returned in auth_config. client_secret follows api_key and
token: encrypted at rest, never returned, accepted in the create body,
and changed afterwards through the credentials subresource. Changing
client_id rebuilds the service's connections, and a connection built
with a pre-registered client is not treated as holding a replaced
registration when an authorization recycles connections. The MCP
service dialog adds optional Client ID and Client Secret fields to the
OAuth section, in all six locales.
Nothing changes for existing services: with client_id empty every
existing path reads the stored registration and registers dynamically
as before, and the authorization code flow, its state, the callback and
the dynamic registration request are untouched. The authorization
server HTTP client is moved into a function that both paths call.
* feat(agent): read chat attachments on demand
Agent turns pasted query-selected attachment excerpts into the prompt before the model could act. List stored files as a manifest so the agent can page and search them through read_attachment.
* fix(agent): preserve attachment access and image reads
* fix(agent): bound attachment cleanup and image processing
* Remove standalone read_attachment tool
* Read attachments and images through read_file
Merge read_attachment into read_file (attachment:// paths, numbered
document images, staged-copy aliasing, query search), return sandbox
images as images, describe images for non-vision models inside the
tool call with bounded concurrency and model-chosen detail/focus,
render image reads in the UI, and record image metadata in Langfuse.
* fix(agent): make attachment pagination complete and bound image reads
* refactor(agent): separate attachment reads and cache image observations
* fix(attachment): read image batches concurrently and harden description cache
- ReadImages authorizes once and describes images in parallel
- start VLM deadlines after a slot is held; longer timeout for full reads
- detach shared description calls from the first caller's context
- skip rewriting unchanged sandbox projections
- strip the description cache from temporary document API responses
- render upload text before calling the vision model
* fix(attachment): number images in document order and polish attachment UI
- return resolved images in document order instead of reverse
- show attachment file names instead of attachment:// IDs in tool titles
- use the shared file icon and a lighter card for chat attachments
* fix(ci): renumber attachment migrations and satisfy lint
Main already took sqlite 000035 and versioned 000116, so the attachment
lookup indexes move to the next free numbers. Also wrap the ReadImages
signature and drop an unused test parameter.
* fix(ci): expect sqlite migrations to reach version 36
The tools a smart-reasoning agent may use were defined in three places
that never checked each other: the agent editor's checkboxes, the stored
allowed_tools, and what registerTools registers. The editor drew from a
hard-coded list that had drifted (search_conversations, a default tool,
had no checkbox), hid stored entries outside that list, and could not
untick a tool whose knowledge base capability was missing. The save API
stored any name. And an empty list could not mean "no tools": three
places treated it as "use the default tools", so clearing every checkbox
gave an agent without a knowledge base search_conversations, while the
editor's preview said it had none.
One source for the tool list: GET /api/v1/agents/tools serves the tools
of AvailableToolDefinitions with their group, danger flag and knowledge
base requirement, the default tools, and the tools other agent settings
register whatever the list says. The editor renders from it, falling
back to the catalog's label for a tool it has no translation for.
Stored values stay visible: a missing capability only blocks ticking a
tool, and stored names the catalog does not offer are shown ticked in
their own section and can be removed.
An empty list now means no built-in tools; only a list that was never
set selects the defaults. tools.EffectiveAllowedTools makes that
decision for tool registration, the session config and the rerank
requirement. Migration 000116 (SQLite 000035) writes the default tools
into the empty list of every existing smart-reasoning agent, so they
keep the tools they ran with. The knowledge base filter follows the
stored list, so such an agent with an "all" scope now gets the same
scope as one that ticked the defaults: bases search_knowledge cannot use
leave it. The editor writes the defaults into an unset list it loads,
so saving does not silently turn the defaults into no tools.
Saving validates the list: retired names are rewritten, switch-managed
and retired skill tools are dropped, names the request adds that no
tool answers to are rejected with a 400 that lists them, and unknown
names already stored are kept so an existing agent can still be saved.
The response reports what was kept or dropped.
* feat(gallery): filter images by source document
Add a gallery toolbar button that opens a paginated, keyword-searchable
document picker; confirming restricts the listing to images owned by
the selected documents. The backend gallery endpoint accepts a
knowledge_ids query param (capped at 50) narrowing chunk_images by the
owning document before de-duplication, so the count query stays index
served.
* feat(gallery): lift knowledge_ids cap via POST body, sortable doc picker
Add POST /knowledge-bases/:id/images accepting the gallery filter as a
JSON body so knowledge_ids escapes the URL-length cap (50 -> 1000, an
abuse guard rather than a transport limit); the GET variant keeps its
cap and both share the contract-constrain logic. The source picker
gains sortable column headers (file name / upload time, newest first
by default), a header select-all that unions and removes whole hit
lists across keyword searches, overflow guards capping the no-keyword
view at the 500 most recent documents, and a wider dialog.
* style(gallery): replace td-token fallbacks and font-size literals with design tokens
styleGuard.test.mjs enforces ratchets: --td-* vars must not carry
fallbacks (theme.css guarantees them) and font sizes must use
--app-text-* tokens. GallerySourcePicker.vue added 4 of each,
pushing the ratchets over baseline.
* fix(gallery): keep shared images in source filter and align picker UI
- Scope the de-duplication probe to the selected documents, so an image
whose newer copy lives in an unselected document is no longer hidden.
- Reset the source filter when the gallery switches knowledge bases.
- Accept an empty POST /images body; drop pruned attribute maps to nil.
- Keep the source filter out of the filter panel's count and clear action;
the empty state's clear still resets it.
- Rework the picker dialog to the BatchTagDialog shell: heading with
subtitle, footer with selection count, clickable rows, debounced search,
select-all toggling against every hit, stale select-all responses dropped.
- Remove the unreachable GET knowledge_ids branch in the API client.
---------
Co-authored-by: tayadwx <tayadwx@users.noreply.github.com>
Co-authored-by: wizardchen <wizardchen@tencent.com>
* fix(deploy): bump paradedb image to v0.25.11-pg17
Batch-importing large knowledge bases on the pinned
paradedb/paradedb:v0.22.6-pg17 image drives PostgreSQL into a
PANIC/crash-recovery loop (corrupted page pointers in shared buffers,
amcheck clean, no OOM), taking every ingest task down with it.
Three independent fixes upstream cover this exact write path, and the
pinned image predates all of them:
- pgvector 0.8.2 fixed a buffer overflow in parallel HNSW index
builds, 0.8.3 fixed possible index corruption during HNSW vacuuming,
and 0.8.4 fixed inserts during HNSW vacuuming; the image ships
pgvector 0.8.1, and the embeddings table maintains three HNSW
halfvec indexes on import.
- pg_search gained WAL-based crash recovery in 0.24.0 (paradedb#4901):
without it, any backend crash corrupts BM25 segment metadata and
turns a single crash into a recovery loop (paradedb#4935).
- PostgreSQL core moved 17.9 -> 17.11; its release notes contain no
fix matching this failure signature, ruling the core out.
Bump the compose image tags to v0.25.11-pg17 (postgres and
langfuse-db-init, prod and dev) and update the docs that pin the old
tag. Fresh installs are covered by the existing schema SQL (verified
against 0.25.11: extensions, BM25 index and HNSW halfvec indexes all
create cleanly). Existing data volumes keep working across the image
swap without any action (keyword and vector queries byte-identical in
testing); ALTER EXTENSION pg_search/vector UPDATE aligns the SQL
catalog afterwards, and migration 000099 is a no-op for 0.25.x by
design. The Helm chart pins a different image line and is left alone.
Fixes#4077
* fix(migrations): upgrade pg_search catalog to 0.25.11 with the image
Swapping in the v0.25.11 image leaves the extension catalog at 0.22.x.
Calling extension functions such as paradedb.version_info() against the
mismatched catalog segfaults the backend and sends the whole server into
crash recovery, so the catalog upgrade is required rather than optional.
- Add migration 000115 to update pg_search 0.22.0-0.25.10 to 0.25.11 and
pgvector 0.8.0-0.8.3 to 0.8.4 when the server ships those versions.
- Skip 000099 on newer images instead of advising UPDATE TO '0.22.6',
which leaves the catalog behind the shared library and crashes.
- Rewrite the upgrade guide as one 0.22.x -> 0.25.11 path with a required
ALTER EXTENSION UPDATE and a note that rollback needs a backup.
- Extend scripts/test_paradedb_upgrade.py to verify 0.22.2 -> 0.25.11 by
default (--to 0.22.6 keeps the old path) and run CONCURRENTLY
migrations outside a transaction like golang-migrate does.
---------
Co-authored-by: LuckVd <LuckVd@users.noreply.github.com>
Co-authored-by: wizardchen <wizardchen@tencent.com>
* feat(system): platform user management — list, enable/disable, reset password, role toggle
Adds a SystemAdmin-only user management panel under platform settings
(System global -> Access). The backend already had repository primitives
and promote/revoke endpoints; this wires the missing service/handler/route
for listing and account-status changes and adds the UI.
Backend
- New GET /system/admin/users: paginated, cross-tenant user list
(offset/limit, limit capped at 200), serialised via ToUserInfo so password
hashes are never exposed; has_more derived with a limit+1 fetch (no COUNT).
- New POST /system/admin/users/status: enable/disable an account.
Disabling revokes all of the user's tokens immediately. Service guards
reject self-disable and disabling the last active system administrator.
- ValidateToken now re-checks is_active on every request, so a disabled
account cannot keep using a previously issued access token.
Frontend
- UserListDialog: table with status/role tags, pagination, in-page
username/email filter, enable/disable and reset-password actions, and
one-click system-admin promote/revoke (reuses existing endpoints) with
confirmation prompts. Reset-password dialog is a sibling (not nested)
dialog so close/cancel/overlay all work.
- All new strings are i18n keys under system.globalSettings.userList in
all six locales (en-US, zh-CN, zh-TW, ja-JP, ko-KR, ru-RU).
Tests: handler unit tests for list pagination/redaction/limit-cap and for
status-change success/guard/404 paths; existing handler/service/router
suites pass.
Co-authored-by: MOSS Agent <noreply@example.com>
* fix(system): make account status changes atomic and validate requests
* refactor(system): streamline settings and add dedicated user management tab
* fix(system): resolve user management CI lint findings
* fix(system): preserve account status during ordinary user updates
---------
Co-authored-by: desksk <26273255+desksk@users.noreply.github.com>
Co-authored-by: MOSS Agent <noreply@example.com>
Co-authored-by: wizardchen <wizardchen@tencent.com>
* feat(wiki): improve graph layout and exploration
* feat(wiki): name graph themes and connect pages to their document summary
- Rewrite selectGraphAnchors on deterministic Louvain communities with
coverage, redundancy and readability rules; clean file-name captions.
- Add group focus bar with switch menu, Esc/background exit, caption pills.
- Count distinct neighbors for link_count from both link directions, and
let ego BFS use the same adjacency so stale in_links do not hide pages.
- Connect each page to its source document summary and leave the index
page out of the graph; return edges as [] for an isolated ego center.
- Keep graph search and type filters available after an empty render.
* fix(wiki): use theme tokens in graph styles and satisfy Go lint
* feat(wiki): label the page shared by a multi-document graph group
fuseWithRRF reads each list's ranks through bestRanks, which ranks every
list on its own by score. Retrievers run concurrently and their results are
appended in goroutine completion order, so neither the order of the lists nor
the order of the hits inside a list may change a chunk's rank.
These tests fail on the pre-#3687 concatenation-order ranking and pass on
main. Refs #3796.
Count distinct coverage across long repetitive runs and preserve HTML-wrapped no-text replies through normalization. Add sanitizer and image-persistence regressions for both cases.
Distinguish vector and keyword result pools, initial and refill phases, and diagnostic decisions from actual retrieval and model calls. Clarify that aggregate counts cover all candidates while detailed samples focus on image vectors, and document the new trace names.
* feat(mcp): support modern and legacy protocol connections
* fix(mcp): preserve annotated headers on modern tool calls
* fix(mcp): load parameter header schemas before tool calls
* fix(mcp): keep a working legacy session when discovery retry fails
Modern method-level 404s stay connected, while an expired SSE session still disconnects. A transient discover failure retries once, and a failed retry keeps the handshake that already succeeded.
* fix(mcp): wrap protocol negotiation lines for the linter
golangci-lint rejects lines longer than 120 characters.
* fix(mcp): retry protocol discovery without dropping the live session
A second initialize on the same transport clears a stateful legacy session when discover returns 404. Probe on a separate connection, and drop cached parameter headers after another client refreshes the directory.
---------
Co-authored-by: wizardchen <wizardchen@tencent.com>
* fix(chat): keep custom metadata on knowledge-chat references
Redis round-trips and graph or analysis result builders dropped knowledge custom metadata, so chat citations lost fields such as course and lesson URLs.
* test(chat): wrap metadata fixtures to satisfy line length lint
---------
Co-authored-by: wizardchen <wizardchen@tencent.com>
* fix(models): align configuration defaults and multimodal workflows
* feat(image): enhance image retrieval diagnostics and filtering
- Implemented `retrieveObservedImagePool` to observe engine calls and record image recall decisions without altering results.
- Added detailed diagnostics in `summarizeImagePool` and `summarizeImageCandidateCut` to track image filtering decisions and scores.
- Introduced tests for image pool diagnostics to ensure accurate filtering and decision recording.
- Updated existing functions to utilize new retrieval and summarization methods for improved observability and accuracy in image handling.
* feat(embeddings): enhance image handling with new formats and message support
- Introduced `EmbeddingImageFormat` to manage image input formats, allowing for both object and messages formats.
- Updated `EmbeddingsSettings` to include new fields for `ImageFormat`, `ImagePrompt`, and `TextAsMessages` to support multimodal embedding workflows.
- Enhanced `Client` methods to build request bodies for images in both formats, ensuring compatibility with vLLM's requirements.
- Added tests to validate the new image message handling and ensure correct request formatting for different scenarios.
- Updated documentation to reflect changes in image input handling and configuration options.
* feat(similarity): add embedding similarity mode for enhanced document scoring
- Introduced a new `similarity` option in `ModelDebugOptions` to score documents and an optional image against a query.
- Updated `ModelDebugDrawer.vue` to support a new input mode for similarity, allowing users to select similarity as an input type.
- Enhanced the UI to display similarity results, including ranked candidates based on cosine similarity.
- Added tests to validate the functionality of the new similarity mode in embedding models.
- Updated localization files to include new strings related to similarity mode in multiple languages.
* feat(embeddings): add Qwen3-VL-Embedding support for multimodal input
- Introduced Qwen3-VL-Embedding model with support for both text and image inputs.
- Updated model configuration files to include compatibility settings for the new embedding type.
- Enhanced tests to validate the functionality of Qwen3-VL-Embedding, ensuring correct handling of inputs and outputs.
- Updated documentation to reflect the new model's capabilities and usage instructions.
* test(models): wrap embedding assertions to satisfy lint
* test(opensearch): isolate HTTP transports between parallel tests
* feat(models): expose embedding input modalities
Whether an embedding model maps images into the same space as text is
what will decide if a knowledge base can store image vectors. The
catalog already had the field, but most multimodal embedding models
were missing it and embedding rows never reported it.
- Catalog: declare input modalities for the Doubao and Tongyi vision
embeddings, the Aliyun multimodal / qwen-vl embedding families and
jina-embeddings-v4, as listed in each vendor's documentation. The
migration baseline changes for exactly these nine entries.
- Model responses resolve capabilities for embedding rows too, so
capabilities.input reflects the catalog merged with spec.input.
- Model editor: an "Image input" switch for embedding models. It follows
the catalog and writes spec.input only when the row differs from it;
picking another catalog model or switching vendor drops the
declaration. Model cards show the image badge for such models.
* feat(embedding): embed images with multimodal embedding models
Adds the image side of an embedder, for models that map images into the
same space as their text vectors so a text query can find an image.
- api: EmbedImage (bytes + MIME type, sent inline as base64 because the
object store is usually unreachable from the vendor) and an
ImageEmbedder implemented by all four protocols, each in the image
shape its reference documents: Ark image_url, DashScope contents[].image,
Gemini inlineData parts, and on the OpenAI shape an object keyed by the
vendor's image_field (Jina: "image"). A plain OpenAI-compatible
endpoint names no image field and takes no images.
- Settings: image_field, max_image_batch_size (default one per request),
max_image_bytes and image_mime_types, filled from vendor docs for the
DashScope multimodal models, gemini-embedding-2 and Jina.
- embedding: an optional ImageEmbedder interface reached through
AsImageEmbedder, so existing Embedder implementations and fakes are
untouched. An embedder takes images only when the catalog (or the
row's spec.input) lists image AND the endpoint can carry one. Images
are checked against the documented limits before any request, then
split at the documented images per request. The concurrency, debug
and Langfuse decorators forward it; logs and traces carry the MIME
type and size, never the bytes.
The migration baseline changes only for the entries whose resolved
embedding settings now carry image limits.
* feat(knowledge): index images by their own vector and recall them
When the knowledge base's embedding model embeds images, each image now
gets a vector of its own next to its caption and OCR chunks, so a query
can find an image by what it shows even where the caption left it out.
Ingestion
- After the caption/OCR chunks are indexed, the multimodal task embeds
the image (embedding.PrepareImage converts and shrinks it to the
vendor's documented limits) and stores it as a new image_vector chunk:
Content is the caption (OCR text when there is none) for reranking and
the answer context; its index row carries the image's vector with
SourceType ImageSourceType. Scanned PDF pages are skipped, their OCR
text serves better. A failure here is logged and never fails the task.
- The image vector gets its own chunk rather than a second index row on
the caption chunk: OpenSearch and Weaviate key documents by ChunkID,
so a second row would overwrite the caption's text vector, and copy,
move and enable/disable all follow chunk IDs.
- CompositeRetrieveEngine.BatchIndexVectors writes precomputed vectors
through each engine's normal BatchIndex, keeping row order (the
composite's de-duplication does not).
- Paths that rebuild vectors from text leave image_vector alone:
syncChunkIndex only syncs its enabled flag, updateChunkVector skips
it, and a caption edit updates its Content only.
- The multimodal task's caption/OCR index rows now set IsEnabled; only
backends with a column default were storing them as enabled.
Retrieval
- A text query scores lower against an image than against text, so when
the model embeds images the document vector search is widened by half
(capped at 500) and run at min(VectorThreshold, 0.1); each store
group's hits are then held to their own threshold before score
normalization: text at VectorThreshold, images at min(VectorThreshold,
0.1). Keyword hits on image rows are dropped, their Content being the
already-indexed caption.
- image_vector hits are searchable and merge like caption hits: parent
context is attached, and the caption is not repeated from ImageInfo.
Adds golang.org/x/image for scaling and WebP/BMP decoding.
* fix(models): report no thinking levels for embedding, rerank and ASR models
Embedding rows now carry capabilities, and the end-to-end run showed them
listing off/auto/minimal/low/medium/high: these references resolve no chat
protocol, and an empty level map reads as "every level supported". A model
without a chat protocol does not think, so its capabilities say so.
* fix(compaction): never read a cancelled turn's stream as a summary
streamSummary selects on the turn's context and the provider stream at
once. When the turn is already cancelled both are ready (providers close
the stream once their context ends), and select picks at random, so a
stopped turn could come back as a completed, partial summary with a nil
error. TestSummarizationIsNotRetriedOnceTheTurnIsCancelled caught it
intermittently in CI and reproduces under -race with several -cpu values.
Check the context before each receive and again when the stream closes.
* feat(rerank): score images with multimodal rerank models
Rerank models that read images can now be sent an image document and
score it against a text query on the same scale as text, which is what a
recall made by an image's own vector needs: a text reranker only sees the
caption, and rejects an image for what the caption left out.
- api: ImageReranker, implemented by the Cohere and NIM shapes. Image
documents go in requests of their own, so text requests keep their
exact shape. NIM sends image-only passages without text, as base64 data
URLs (its VLM reranking reference requires both). The Cohere shape sends
{"<image_field>": data URI} documents and asks for no echo of them.
- The image settings embeddings already had (image_field,
max_image_batch_size, max_image_bytes, image_mime_types) move into a
shared ImageInput embedded in both settings; resolved embedding settings
serialize exactly as before.
- Catalog: jina-reranker-m0 and nvidia/llama-nemotron-rerank-vl-1b-v2 take
text and image. Jina names "image" documents; its base64 form is not
shown in any reranker example, so the data URI its embeddings reference
documents is used and marked unverified. NVIDIA lists its six formats
and 512 passages per request.
- rerank: an optional ImageReranker reached through AsImageReranker, gated
on the model's catalog input and the endpoint; images are checked against
the documented limits before any request, scores are normalized like
text, and the debug and Langfuse decorators forward it without logging
image bytes.
- Image preparation (format conversion, shrink to fit) moves from the
embedding package to internal/models/imageprep, since rerank needs it
too.
* feat(retrieval): keep a vector hit's own similarity through fusion
Hybrid fusion replaces a hit's Score with a rank-based RRF score. That is
right for ordering, but it erases the evidence reranking needs to judge an
image found by its own vector: how close the vector actually was. Record
the engine's similarity on each vector hit (IndexWithScore.VectorScore)
before normalization and fusion rewrite Score, and carry it onto the
search result (SearchResult.VectorScore, not serialized).
* feat(reranking): judge image hits by their image, not only their caption
An image found by its own vector was reranked on its caption and OCR text,
so a text reranker rejected it for exactly what the caption left out.
- With a reranker that reads images and a LoadImage callback, image_vector
hits are scored by their image (prepared to the model's limits) on the
same scale as text, and pass or fail the same threshold. A hit whose
image cannot be read, prepared or scored falls back to its text.
- With a text reranker, its verdict stands for images that are mostly
text (OCR of 200 characters or more). A pictorial hit it rejects is kept
when its vector similarity (VectorScore) reaches Options.ImageKeepScore:
at most two, strongest vector first, appended after the ranked results
and marked kept_by=image_vector. This also returns an image when no text
passes at all.
- Diagnostics report images_scored and images_kept.
* feat(rerank): read image hits' images in every rerank path
The chat pipeline, the agent search_knowledge tool and the hybrid-search
API now pass the rerank stage a way to read an image hit's image and an
image keep score, so a multimodal reranker scores images by what they show
and a text reranker can no longer drop a pictorial image its caption
undersells.
- KnowledgeBaseService.ReadChunkImage reads the first image of a result's
image_info from the storage of its knowledge base (the knowledge base's
tenant, so shared knowledge bases read from their owner's storage),
capped at 32 MB. Plain http(s) images go through the SSRF-safe
downloader.
- The backend resolution the image multimodal task used moves into a
shared knowledgeImageReader, so ingestion and reranking find an image in
the same place.
- reranking.ImageKeepScoreFor: an image is kept over a text reranker only
when its vector was at least as close as a text hit had to be, and never
below 0.25 (empirical).
* feat(chat): show a vision model the images its answer rests on
An image recalled by its own vector reached the answer as its caption only,
so a vision model could not answer from what the caption left out.
- Knowledge QA: INTO_CHAT_MESSAGE reads, for a model that supports vision,
the images of the contexts that rest on an image vector match (at most
three distinct ones, prepared to what every vision API takes: PNG, JPEG,
WebP or GIF within 5 MB), attaches them after the user's own images, and
names the contexts they belong to.
- Agent: search_knowledge attaches the same images when the agent's model
supports vision (the agent describes tool images to models that cannot
see them, and these already carry captions). Stored history drops them;
they are read again from storage.
- An image hit and its caption hit read the same once merged, and
de-duplication keeps either. The kept copy now inherits the image
(image_vector_match), in the pipeline's exact and partial-overlap
de-duplication and in the agent tool's.
- Results the rerank stage kept outside its top-k (kept_by) no longer fall
to the later top-k cuts: the pipeline's FilterTopK and the agent tool's
MMR and limit let them ride along after the ranked results.
* docs(website): describe how image hits are reranked and shown to vision models
* Fix image evidence preservation and model source mapping
* fix(knowledge): claim cloned and released document images in the catalog
#3493 binds images at parse time (bindStoredImages), which covers ingestion
but not the two paths that move image ownership:
Clone. A copied image is written as a new object, yet nothing claimed it for
the destination knowledge, so the KB file proxy answered 403 and cloned
documents rendered without images. The copy now goes through SaveBytes into
the servable exports/ namespace (CopyFile wrote to the knowledge-scoped
upload layout the proxy rejects), is claimed by the destination knowledge,
and CloneChunk / FAQ clone bind the handles left in chunk content and
image_info.
Delete. Release only looked at multimodal ImageInfo, which stays empty for
documents whose images live in markdown alone, so those objects outlived the
knowledge that owned them. The release set is now the union of ImageInfo URLs
and the bindings recorded for the knowledge being removed, with source_file
excluded so reparse and cleanup keep the original document.
The parse-path claim from the earlier attempt is dropped: ProcessDocument
already gets it from bindStoredImages, and the removed test only string
matched that call in the source. Every claim path stays best-effort,
including the clone path, which used to fail the whole clone and delete the
fresh copy when a single Bind errored.
* fix(knowledge): keep markdown-only images out of the pre-reindex cleanup
cleanupKnowledgeResources runs before a knowledge is re-indexed -- a manual
update, a reparse, a move with reparse -- not before it is removed. Unioning
in the catalog bindings there released a solely owned markdown-only
attachment, deleteExtractedImages deleted the file, and the catalog file
service marked the resource deleted. The re-claim that runs after the cleanup
resolves through a state=active lookup, so it could never bind that handle
again: the republished body was left pointing at a deleted image.
Cleanup collects ImageInfo URLs alone again. The paths that do remove a
knowledge entry (executeKnowledgeDelete, ProcessKBDelete) keep the union, which
is what lets markdown-only images be released when the knowledge actually goes
away.
Reported by @lyingbug in review on #3752.
---------
Co-authored-by: tayadwx <tayadwx@users.noreply.github.com>
* feat(models): expose embedding input modalities
Whether an embedding model maps images into the same space as text is
what will decide if a knowledge base can store image vectors. The
catalog already had the field, but most multimodal embedding models
were missing it and embedding rows never reported it.
- Catalog: declare input modalities for the Doubao and Tongyi vision
embeddings, the Aliyun multimodal / qwen-vl embedding families and
jina-embeddings-v4, as listed in each vendor's documentation. The
migration baseline changes for exactly these nine entries.
- Model responses resolve capabilities for embedding rows too, so
capabilities.input reflects the catalog merged with spec.input.
- Model editor: an "Image input" switch for embedding models. It follows
the catalog and writes spec.input only when the row differs from it;
picking another catalog model or switching vendor drops the
declaration. Model cards show the image badge for such models.
* feat(embedding): embed images with multimodal embedding models
Adds the image side of an embedder, for models that map images into the
same space as their text vectors so a text query can find an image.
- api: EmbedImage (bytes + MIME type, sent inline as base64 because the
object store is usually unreachable from the vendor) and an
ImageEmbedder implemented by all four protocols, each in the image
shape its reference documents: Ark image_url, DashScope contents[].image,
Gemini inlineData parts, and on the OpenAI shape an object keyed by the
vendor's image_field (Jina: "image"). A plain OpenAI-compatible
endpoint names no image field and takes no images.
- Settings: image_field, max_image_batch_size (default one per request),
max_image_bytes and image_mime_types, filled from vendor docs for the
DashScope multimodal models, gemini-embedding-2 and Jina.
- embedding: an optional ImageEmbedder interface reached through
AsImageEmbedder, so existing Embedder implementations and fakes are
untouched. An embedder takes images only when the catalog (or the
row's spec.input) lists image AND the endpoint can carry one. Images
are checked against the documented limits before any request, then
split at the documented images per request. The concurrency, debug
and Langfuse decorators forward it; logs and traces carry the MIME
type and size, never the bytes.
The migration baseline changes only for the entries whose resolved
embedding settings now carry image limits.
* feat(knowledge): index images by their own vector and recall them
When the knowledge base's embedding model embeds images, each image now
gets a vector of its own next to its caption and OCR chunks, so a query
can find an image by what it shows even where the caption left it out.
Ingestion
- After the caption/OCR chunks are indexed, the multimodal task embeds
the image (embedding.PrepareImage converts and shrinks it to the
vendor's documented limits) and stores it as a new image_vector chunk:
Content is the caption (OCR text when there is none) for reranking and
the answer context; its index row carries the image's vector with
SourceType ImageSourceType. Scanned PDF pages are skipped, their OCR
text serves better. A failure here is logged and never fails the task.
- The image vector gets its own chunk rather than a second index row on
the caption chunk: OpenSearch and Weaviate key documents by ChunkID,
so a second row would overwrite the caption's text vector, and copy,
move and enable/disable all follow chunk IDs.
- CompositeRetrieveEngine.BatchIndexVectors writes precomputed vectors
through each engine's normal BatchIndex, keeping row order (the
composite's de-duplication does not).
- Paths that rebuild vectors from text leave image_vector alone:
syncChunkIndex only syncs its enabled flag, updateChunkVector skips
it, and a caption edit updates its Content only.
- The multimodal task's caption/OCR index rows now set IsEnabled; only
backends with a column default were storing them as enabled.
Retrieval
- A text query scores lower against an image than against text, so when
the model embeds images the document vector search is widened by half
(capped at 500) and run at min(VectorThreshold, 0.1); each store
group's hits are then held to their own threshold before score
normalization: text at VectorThreshold, images at min(VectorThreshold,
0.1). Keyword hits on image rows are dropped, their Content being the
already-indexed caption.
- image_vector hits are searchable and merge like caption hits: parent
context is attached, and the caption is not repeated from ImageInfo.
Adds golang.org/x/image for scaling and WebP/BMP decoding.
* fix(models): report no thinking levels for embedding, rerank and ASR models
Embedding rows now carry capabilities, and the end-to-end run showed them
listing off/auto/minimal/low/medium/high: these references resolve no chat
protocol, and an empty level map reads as "every level supported". A model
without a chat protocol does not think, so its capabilities say so.
* fix(compaction): never read a cancelled turn's stream as a summary
streamSummary selects on the turn's context and the provider stream at
once. When the turn is already cancelled both are ready (providers close
the stream once their context ends), and select picks at random, so a
stopped turn could come back as a completed, partial summary with a nil
error. TestSummarizationIsNotRetriedOnceTheTurnIsCancelled caught it
intermittently in CI and reproduces under -race with several -cpu values.
Check the context before each receive and again when the stream closes.
* feat(knowledge): put image vectors behind a knowledge-base switch, off by default
Image vector indexing and recall used to turn on whenever the knowledge
base's embedding model declared image input. A model that takes images is
often chosen for text alone, so an upgrade would have added an embedding
call per image, widened vector recall 1.5x and lowered the image threshold
to 0.1 for those knowledge bases without anyone asking.
ImageProcessingConfig gains image_vector_enabled (default false; stored
JSON without the key reads as off, so existing knowledge bases stay off
with no migration). Both sides now need the switch and the model:
- indexImageVector returns before touching the model unless the KB opted
in (KnowledgeBase.IsImageVectorEnabled, which also needs vector indexing).
- applyImageRecall resolves the embedding model only when some KB in the
search opted in, and records the opted-in KBs per store group
(storeGroup.ImageKBIDs). Only those groups widen the pool and lower the
threshold; image hits of any other KB, including ones indexed before the
switch was turned off, are dropped.
The KB editor shows the switch in the image processing section, with a
warning when the selected embedding model does not declare image input;
docs describe the switch, its cost and what turning it off does.
* fix(knowledge): leave image vectors behind when cloning into a KB that is off
CloneChunk copied every chunk of the source document and then CopyIndices
for all of them, so copying a document from a knowledge base with image
vectors on into one with the switch off (same model and store) still
created image_vector chunks and their index rows, bypassing the switch
that indexImageVector honours.
Image vector chunks are now dropped from the copy when the target has not
opted in. Every engine's CopyIndices copies only the rows of chunks in the
mapping, so their index rows stay behind too.
* fix(search): refill the vector pool past stale image vectors
Image hits of a knowledge base whose switch is off were dropped only after
the engine had ranked and cut its results at TopK. Image vectors indexed
before the switch was turned off could fill that pool and push out valid
text hits: with MatchCount 5 the pool is 50, and 50 stale image rows
ranked above the text left the search empty.
No engine can filter rows by source type (Postgres and SQLite do not even
take ExcludeChunkIDs), so the exclusion cannot move into the query. When
the document vector pool comes back full and holds stale image rows, that
search alone runs again on a pool twice as large, until it holds TopK rows
that are not stale, the index runs out, or the pool reaches
maxRetrievalPoolSize (at most four extra calls from a pool of 50). The pool
is then cut back to TopK such rows, matching an engine-side exclusion
unless more than maxRetrievalPoolSize-TopK stale rows rank above the text.
* feat(i18n): translate the image vector switch and image input keys into zh-TW
The zh-TW locale arrived from main after this branch added five keys: the
knowledge base's image vector switch (label, description, unsupported-model
warning) and the embedding model's image input flag (label, description).
* fix(knowledge): leave image vectors behind when moving into a KB that is off
A reuse_vectors move relocates a document's chunks and index rows in place:
MoveKnowledgeIndices rebinds the rows by document ID and
MoveChunksByKnowledgeID rebinds the chunks. Moving a document from a
knowledge base with image vectors on into one with the switch off therefore
carried its image_vector chunks and their vectors along, the same bypass the
clone path had.
When the target has not opted in, the image_vector chunks are now deleted
during the move, their index rows first and then the chunks, so a retry
finds the chunks again rather than leaving orphaned rows. A target that
opted in still receives them unchanged.
* fix(retriever): keep image vectors out of keyword-only engines
BatchIndexVectors handed image rows to every engine of the composite,
including one that serves keyword retrieval alone (Elasticsearch v7 next to
a vector store). There the row holds nothing but the image's caption, which
the caption's own chunk already indexes, and retrieval discards every
keyword hit on it.
Image rows now go only to engines that serve vector retrieval. An engine
that serves both keeps one row for both kinds, so its keyword search still
meets them; the search side handles that.
* fix(search): refill the keyword pool past image rows
Every engine that serves both kinds of retrieval stores one row per index
entry and runs its keyword search over that row's content, so an image
vector row, whose content is its caption, is a keyword hit wherever the
caption's own chunk is. filterImageHits drops all of them, but only after
the engine has cut its ranking at TopK, so they crowded out text and caption
hits; a keyword ranking that put the image rows first came back empty.
The keyword pool is now refilled the way the vector pool is refilled past
stale image vectors: when it came back full and held image rows, the
keyword search runs again on a pool twice as large, up to
maxRetrievalPoolSize, and is cut back to TopK hits that are kept.
Leaving the rows out of the keyword index instead would mean writing them
without searchable content (Milvus and Tencent VectorDB derive a BM25
sparse vector from it, and how they take an empty one is unverified) or a
source-type filter in every engine's keyword query (ten engines, and
filterable fields that existing collections lack).
* revert: let image vectors move with the document into a KB that is off
This reverts commit e259977fe915f7d0bc30c4b02bc7af04da1c8dd4.
Deleting the image vector index rows by chunk ID before the move is not
reliable: the Weaviate and Elasticsearch v8 delete wrappers ignore partial
failures, and OpenSearch rejects more than 1000 IDs with ErrBatchTooLarge.
A partial delete followed by the chunk delete leaves index rows whose chunks
are gone, which nothing ever cleans up.
Without it, the image_vector chunks and their index rows move together
with the document. While the target's switch is off they are filtered at
query time (the pool refill keeps them from crowding out text), they are
removed with the document on delete, reparse or knowledge base delete, both
chunks and index rows by knowledge ID, and they become active again if the
target turns the switch on. The clone path keeps dropping them, since there
the rows are copied rather than moved.
* fix(search): keep the image row refill from losing hits it already had
refillPool replaced a pool with the answer to each larger search. A refill
that answered only in part (RetrieveResult.Error, swallowed into a warning
by retainPartialResults, as when some collections of the store did not
answer) could hold fewer text rows than the complete smaller pool, or none:
40 stale image rows above 10 text came back from a partial refill as the
40 image rows alone, and the search lost all 10 text hits. A refill that
failed outright failed the whole store group, discarding a first round that
had succeeded.
A refill is now best effort. A failed or incomplete refill search stops
the refill and leaves the last complete pool in place, cut back to TopK
kept rows as before, so a refill can no longer leave a search worse off
than it was without it. Merging the partial answer into the pool was not
done: its rows would need deduplicating and its ranking is cut at a
different TopK over a different set of collections, while keeping the
previous pool is exact.
* docs(knowledge): say what happens to image vectors in a KB that is off and what the refill costs
The image vector section now says that with the switch off, image vectors
that were indexed before it was turned off, or that came along when the
document was moved in from a KB that has it on, are kept but filtered at
query time, are removed when the document is deleted or reparsed or the
KB is deleted, and are recalled again once the switch is turned on; a copy
into such a KB leaves them behind.
It also states the cost of keeping dropped image rows from crowding text
out of the pools: the vector and keyword pools are searched again with
TopK doubled up to the 500 candidate cap, which adds queries for store
groups that hold such rows, and text can still be missed when more than
about 500 candidates are image rows. A failed or partial refill keeps the
previous complete pool.
* fix(search): log unexpected refill result sets, and describe the refill stop condition precisely
* fix(datasource): omit last_sync_cursor from the data source list response
The settings page polls GET /datasource every few seconds during a sync,
and connector cursors can grow to megabytes. No list consumer reads the
cursor, so NewDataSourceResponses now blanks it; detail, create and
update responses still return it through NewDataSourceResponse.
* feat(datasource): add Seafile connector with fingerprint-based incremental sync
Sync folders and files from one Seafile library per data source. The
connector walks the selected scope one directory level at a time,
downloads files through the link + fileserver flow without credentials,
and reconciles deletions against a per-file oid/mtime/size fingerprint
cursor that is checkpointed every 50 mutations.
- resource ids are "<repo_id>:<path>"; ancestors collapse, one library
- per-file failures become coded error items and keep the path pending
- directory failures and Retry-After > 60s abort without deletions
- forced full runs keep the old cursor as a deletion baseline
- API token never reaches cursors, metadata, logs or error text
- share the supported import extension set through internal/utils
* feat(datasource): add Seafile frontend connector and docs
Wire the Seafile data source into the editor dialog, channel labels
and the five locales, and document how to connect a Seafile 10.0.1
library.
- connector definition with base_url + API token fields and icon
- picker guard: one library per data source, at least one selection
- "library" resource type and icon in the lazy tree
- channel label in the knowledge base filter, document views and chat
- i18n for labels, guide steps and the eight seafile_* sync error codes
- website-docs integration guide, data source and extension point doc
updates, and Seafile in the README data source lists
---------
Co-authored-by: zaqqmm <q-zhang10@qq.com>
* fix(chat_pipeline): treat non-JSON model refusals as skipped graph extraction
When a chunk carries nothing extractable (e.g. a table-of-contents page),
the LLM correctly answers with a prose refusal such as "抱歉…". parseOutput
then fed that prose to json.Unmarshal, failing with a confusing
"invalid character 'æ'" (the first byte of a CJK character), marking the
chunk task GRAPH_EXTRACT_FAILED and letting asynq replay the identical
doomed LLM call up to the retry limit.
Classify responses that contain no JSON structure at all (no '{' or '[')
as errModelDeclined and complete the extraction with an empty graph so the
task succeeds as an explicit skip. Malformed or truncated JSON (structure
present) still fails and retries as before.
Fixes#3600
* fix(chat_pipeline): keep empty model responses retriable in graph extraction
An empty response is usually transient (gateway returning 200 with no
content, a reasoning model spending its whole budget on reasoning,
content filtering), and a retry often succeeds. Only non-empty prose
with no JSON structure is treated as a declined extraction.
* fix(graph): skip prose refusals only in the async chunk task, keep truncation retriable
ParseGraph no longer turns a prose answer into an empty graph. It returns
an error wrapping ErrModelDeclined, and ChunkExtractService.Handle is the
only caller that treats it as a skip (span output skipped=model_declined).
The /initialization "try extract" endpoint and query-side entity extraction
report the refusal as a failure again, so the graph settings form no longer
gets its few-shot examples replaced with an empty result.
Extractor.Extract drops the ErrModelDeclined marker when finish_reason is
"length": prose with no JSON because the output budget ran out is
truncation, and asynq should retry it.
* fix(graph): retry every truncation spelling, not only finish_reason=length
Extract kept a prose answer retriable only when FinishReason was exactly
"length". max_tokens / max_output_tokens (and case/space variants that
IsLengthFinishReason already accepts), a stream that broke before the stop
event ("incomplete") and an adapter that reports no reason were still read
as a refusal, so the async chunk task skipped the chunk for good.
Only a reason that proves the model stopped on its own now counts as a
refusal. Ollama's non-streaming Chat also forwards done_reason, so a
num_predict cut-off is reported as "length" instead of an empty string.
* fix(graph): only treat a response with no JSON anywhere as a refusal
The refusal check looked at the first extracted fence, so a prose fence
followed by a JSON fence was skipped as a refusal instead of failing as a
retriable parse error.
---------
Co-authored-by: LuckVd <LuckVd@users.noreply.github.com>
Co-authored-by: wizardchen <wizardchen@tencent.com>
* fix(kb): let update API set vlm_config
UpdateKnowledgeBaseRequest only carried name/description/config, so the
PUT /knowledge-bases/:id endpoint could never change a knowledge base's
multimodal (VLM) config, even though CreateKnowledgeBase accepts a
top-level vlm_config. Thread an optional vlm_config through the handler
and service so the update path mirrors create (nil = no change).
Fixes#1723
* test(kb): pass the vlm_config argument in tests added on main
* fix(kb): accept only model-managed vlm_config fields on update
The update API copied the request's VLMConfig wholesale, so a caller
could set the legacy ModelName/BaseURL/APIKey/InterfaceType fields and
have the VLM client call BaseURL directly, outside model management and
its SSRF checks. Only Enabled/ModelID/DescriptionLanguage/
CustomInstructions are taken now; legacy fields keep their stored value.
A referenced model must exist and be a VLLM model (400 otherwise), and
disabling clears ModelID, matching the initialization config endpoint.
* fix(kb): validate and gate vlm_config on the update API
- Enforce the 4000-character custom_instructions cap
(types.ValidateKnowledgeBasePromptInstructions), as create and
/initialization/config already do.
- vlm_config is a KB setting: require kbSettingsAccess (owner workspace
or admin share) like /initialization/config, so share editors get 403.
- Stored legacy model_name/base_url keep IsEnabled() true on their own,
so disabling returned 200 but left VLM on, and managed -> disabled fell
back to the old endpoint. Clear them when the request enables a managed
model_id, or disables VLM without echoing back the stored
model_name+base_url (GET-then-PUT keeps legacy on). Request legacy
fields are only compared, never written. Enabling without model_id on a
non-legacy KB is now a 400 instead of a silent no-op.
- Document the vlm_config semantics in the KB API reference.
* fix(kb): keep the legacy VLM endpoint only for pure legacy knowledge bases
CreateKnowledgeBase stores vlm_config as sent, so a managed model_id can
sit next to legacy model_name/base_url; resolveVLM then uses the managed
model. The update's keep-legacy paths (disable echoing the stored legacy
fields, enabled=true without model_id) cleared model_id but kept the
legacy fields, so IsEnabled() stayed true and image calls moved to the
stored base_url.
Those paths now apply only when no model_id is stored. On a mixed config
a disable clears everything, and enabled=true without model_id is a 400,
the same as on any managed knowledge base.
---------
Co-authored-by: wizardchen <wizardchen@tencent.com>
* fix(knowledge): delete written chunks when the storage quota check fails
processChunks writes the chunks before the storage quota check. When the
check fails, or the tenant cannot be re-read for it, the knowledge is marked
failed and the function returned without removing those chunks, so they
stayed active (deleted_at IS NULL, is_enabled = true) under a failed,
disabled knowledge. The BatchIndex failure path already deletes them; do the
same in both quota branches. Nothing has been indexed at that point, so only
the chunk rows need removing.
Fixes#3648
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* style(knowledge): keep the processChunks doc comment on processChunks
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: wizardchen <wizardchen@tencent.com>
* fix(qdrant): 复制索引改用服务端返回的游标,重复游标报错并给分页加跳数上限
CopyIndices 用"上一页最后一个点的 id"当游标(repository.go:987)。Qdrant 的
scroll offset 是**包含**语义 —— proto 里写的是 "Start with this ID",实测下一页
正是从该 id 本身开始返回,所以每翻一页都会把上一页的最后一个点再读一次、再写一份
到目标库。服务端本来就把下一页该用的游标放在 ScrollResponse.next_page_offset
("Use this offset for the next query")里,而客户端只在 ScrollAndOffset() 中返回它,
本函数调用的 Scroll() 恰好把它丢掉了;终止条件也只能退化成"这一页比 64 短"。
在真实 Qdrant 1.19.1 上实测:150 个源 chunk 复制出 152 个目标点,chunk-63 与
chunk-126 各被复制两次(每个页边界一个),totalCopied 同步虚高。源库只要超过一页
(>64 个 chunk)就会命中,不需要服务端有任何异常行为。
本次修改:
- 改用 q.client.ScrollAndOffset,游标直接取服务端返回的 next_page_offset;终止
条件改为"服务端没有下一页"(next_page_offset == nil),不再用短页推断读完。
- 记录用过的游标,重复即返回 "copy indices made no progress at cursor ...",
检测点在整页处理之前,重复的那一页不会再多写一份。
- 分页跳数上限 maxCopyPaginationHops(10000 页);触顶打印 Warn 并返回错误,
而不是把这一轮复制当成成功。
- 修复后同一份数据在真实 Qdrant 上测得 150 个目标点、0 重复。
回归用例用假 gRPC 服务端(拦截 unary RPC,对齐 repository_test.go 的
newInterceptedQdrantClient)复刻真实服务端的游标语义:150 个源 chunk 必须各复制
一次(修复前 152 个点、2 个重复);游标恒定不动的源端必须报 no progress
(修复前 5 秒写入 3127040 个点仍未返回);一直推进但永不结束的源端在第 10000 页
被拦下。
* fix(qdrant): drop the CopyIndices page cap
10000 pages of 64 points capped a copy at 640k points and failed the
whole clone beyond that. The scroll walks every point of the source
knowledge base (a single-knowledge clone included), so a cap derived from
the chunk map would cut off small clones out of large bases too.
next_page_offset only moves forward, so the repeated-cursor check already
stops a walk that cannot finish, and the task context bounds the rest.
---------
Co-authored-by: linus-liu-web <11640009+linus-liu-web@users.noreply.github.com>
Co-authored-by: wizardchen <wizardchen@tencent.com>
* fix(skills): skip vendored dep trees in install verification script enumeration
sortedScriptPaths fed every .py/.js/.sh in the bundle into one shell 'for
f in ...' command. A skill that vendors a scientific venv (pandas/scipy/
matplotlib etc.) carries thousands of .py files under .venv/, and the
generated command exceeds the exec single-argument limit (MAX_ARG_STRLEN,
128KiB): /bin/sh fails with 'argument list too long' (exit 255) before
any check runs, so no dependency-heavy skill can ever install.
Vendored trees are installed dependencies, not scripts the model can
name; their health is already covered by the dependency verification
passes. Skip .venv/ and node_modules/ prefixes in sortedScriptPaths,
which fixes the tree check, the per-language parse passes and the
runtime prerequisite pass at once.
Verified by installing a 4862-file / 105MB quant skill (pandas+numpy+
scipy+statsmodels+matplotlib venv, real interpreter binary instead of
symlinks since zips cannot carry them): install failed before the fix,
reaches ready after it.
* fix(skills): skip vendored trees at any depth, not only at the bundle root
Bundles are author-zipped, so tools/.venv/ or sub/package/node_modules/
are as legal as root-level trees and enumerated just the same. The
filter now matches vendored trees under any prefix; nested placements
are covered by a regression test.
---------
Co-authored-by: vicfei <vicfei@users.noreply.github.com>
Sweep A only selects pending/processing/finalizing, so a row that reaches a
terminal state while its attempt is still open is never revisited: its spans
stay "running" and the document timeline shows a permanent 进行中. Found in
production with four root spans stuck for 11 and 27 days.
- housekeeping: add Sweep D (reapTerminalSpans) closing spans still open on
terminal rows, carrying the row own error_message so the timeline still
names the real cause. A self-healing backstop for every failure path that
forgets to close its attempt, including rows stranded by older releases.
- span tracker: OpenAttempt now cancels spans left open by earlier attempts
(ATTEMPT_SUPERSEDED). A reparse used to open its new root alongside the
previous attempt dead root, which is what made historical runs look
like they had been reactivated.
Co-authored-by: asmh1989 <minhua.sun@velavigo.com>
processChunks marked the knowledge failed and returned nil when BatchIndex
failed, so ProcessDocument acked the task and the configured document-task
retries never ran. A short embedding or vector-store outage left the row
permanently failed; unchanged data-source syncs did not reprocess it.
While attempts remain, still clean up the partial chunks and vectors but
keep the row processing and return the error to the queue. The final
attempt (or a caller without a retry loop) records the failure as before.
newS3Client forced path-style for every non-AWS endpoint, so a COS
endpoint such as https://cos.ap-shanghai.myqcloud.com sent requests to
cos.<region>.myqcloud.com/<bucket>/<key>. COS rejects path-style for
buckets created from 2024-01-01, so STORAGE_TYPE=s3 could not reach new
COS buckets, and force_path_style=false had no way to turn it off.
Treat *.myqcloud.com like AWS and use virtual-hosted style. An explicit
force_path_style still wins, and other S3-compatible endpoints keep
path-style.
Fixes#3134
Signed-off-by: Ankit Jha <ankit.jha@tradomate.one>