Skip to content

fix(llm): honor vector_dis_threshold and validate results in VectorIndexQuery - #412

Open
lplalbert wants to merge 9 commits into
apache:mainfrom
lplalbert:fix/vector-index-query-dis-threshold
Open

lplalbert wants to merge 9 commits into
apache:mainfrom
lplalbert:fix/vector-index-query-dis-threshold

Conversation

@lplalbert

@lplalbert lplalbert commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Refs #107 (Tiny Task: fix TODO/FIXME in LLM code)

What

VectorIndexQuery (chunk retrieval in the GraphRAG pipeline) hard-coded dis_threshold=2
and silently dropped the documented VECTOR_DIS_THRESHOLD knob (default 0.9), unlike its
sibling SemanticIdQuery. It also carried a TODO about validating result format before
the downstream join/rerank. Review on this PR surfaced that routing one shared knob through
both consumers couples chunk pruning to keyword-to-vertex matching, so each path now keeps
its own configured default and the request field is scoped to keyword matching.

Behavior (default unchanged)

  • Chunk retrieval gets its own CHUNK_DIS_THRESHOLD setting (default 2.0, the previous
    hard-coded value): default filtering is unchanged and only prunes clearly-off candidates.
  • VECTOR_DIS_THRESHOLD (default 0.9) stays dedicated to SemanticIdQuery keyword→vertex
    matching and no longer affects chunk retrieval.
  • Request field vector_dis_threshold is optional and scoped to keyword matching: omitted →
    each path resolves its own configured default; an explicit value is a per-call override for
    SemanticIdQuery only, and chunk retrieval always prunes at CHUNK_DIS_THRESHOLD. 0
    means "exact matches only" wherever it applies; the flows pass values through verbatim
    (x or default swallowed falsy values before).
  • Milvus retrieval returns chunk text verbatim: JSON-shaped text (123, true,
    {"a": 1}) and empty-string properties round-trip unchanged instead of being decoded or
    filtered out. Gremlin-example retrieval still returns {"query", "gremlin"} dicts:
    the stored JSON text is parsed at GremlinExampleIndexQuery, which owns that shape.

Changes

  • HugeGraphConfig.chunk_dis_threshold: float = 2.0; VectorIndexQuery (parameter renamed
    chunk_dis_threshold) falls back to it; VectorQueryNode keeps the request threshold out
    of chunk retrieval entirely.
  • run() passes the threshold to VectorStoreBase.search(..., dis_threshold=...).
  • _check_results_format() drops non-string entries with a warning so downstream
    " ".join/rerank can rely on List[str] (now a pure type guard: every backend returns
    stored text verbatim).
  • Milvus store: search()/get_all_properties() return the stored property text as-is
    (the json.loads decode is gone; get_all_properties() no longer drops empty strings),
    with the verbatim string round-trip documented in those docstrings (83ba325).
  • Gremlin-example index: GremlinExampleIndexQuery._get_match_result parses each stored
    example back into its {"query", "gremlin"} dict. The first revision (129cc48) made
    the store return property text verbatim and thereby regressed this index (dicts stored
    as JSON text reached _format_examples as strings); the decode belongs at the query
    operator, which owns the example shape, so chunk text keeps its verbatim round trip.
  • RAGRequest/GraphRAGRequest.vector_dis_threshold: Optional[float] = None; flows pass
    explicit values through verbatim; the demo batch path follows the configured settings;
    both Query descriptions state the keyword-only scoping (2e68185).
  • config.md documents both knobs.
  • Tests: test_vector_index_query.py (settings fallback, explicit override, falsy 0);
    test_vector_query_node.py pins the request threshold out of chunk retrieval;
    test_rag_request_defaults.py adds API-to-store chain tests (request → flow → node →
    store search at CHUNK_DIS_THRESHOLD for omitted/explicit values);
    test_optional_vector_clients.py covers the Milvus JSON-shaped-text round trip.

Validation (actually run; offline only)

  • Red-green: 5 new regression tests fail on the pre-fix tree and pass after the fixes.
    Round 2 (aeed04e/2e68185/83ba325): red-green for the gremlin-example regression
    (stored JSON text decoded at the query operator) adds 2 tests (1310→1312); request
    descriptions clarified; the string round-trip docstrings moved here from fix(llm): align VectorStoreBase annotations and finish its docstrings #414 beside
    the implementing code (83ba325).
  • SKIP_EXTERNAL_SERVICES=true uv run --extra dev pytest -q hugegraph-llm/src/tests →
    1312 passed, 12 skipped, 2 failed (1310 before the round-2 tests) — the 2 failures are
    pre-existing on Windows
    (test_external_config.py asserts POSIX 0600 file-mode bits) and unrelated to this diff
  • SKIP_EXTERNAL_SERVICES=true uv run --extra dev pytest -q hugegraph-llm/src/tests/integration →
    136 passed, 5 skipped
  • uv run --extra dev ruff format --check / ruff check on changed files → clean
  • uv run --extra dev ty check hugegraph-llm/src/hugegraph_llm → 263 diagnostics;
    file-scoped comparison against the pre-change tree: 0 new (2 pre-existing in changed
    files). Round 2: 1↔1 diagnostics, zero new (pre-existing
    VidEmbeddingsRefreshRequest.expected_graph)
  • Real-provider verification: none (offline tests only; the Milvus round trip is pinned by a
    collection double emulating the server-side query filter)

Refs #107

🤖 Generated with Claude Code

@github-actions github-actions Bot added the llm label Nov 9, 2026

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: yes. Summary: chunk retrieval switches from the hard-coded dis_threshold=2 to VECTOR_DIS_THRESHOLD (default 0.9), so every existing FAISS or Milvus user loses chunks with cosine similarity at or below 0.55 without opting in, and the suggested VECTOR_DIS_THRESHOLD=2.0 escape hatch also loosens keyword-to-vertex matching in SemanticIdQuery.

# TODO: check format results
context["vector_result"] = results
log.debug("KNOWLEDGE FROM VECTOR:\n%s", "\n".join(rel for rel in context["vector_result"]))
results = self.vector_index.search(query_embedding, self.topk, dis_threshold=self.vector_dis_threshold)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: every /rag flow and the Gradio demo pass 0.9 here, and on squared-L2 stores (FaissVectorIndex, Milvus L2) that drops chunks with cosine similarity at or below 0.55, which the old 2 kept, while the only way back (VECTOR_DIS_THRESHOLD=2.0) also loosens SemanticIdQuery keyword matching. Give chunk retrieval its own threshold setting defaulting to 2.0, so existing results stay the same and the two thresholds stay independent.

@imbajin imbajin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: yes. Summary: The configured threshold does not restore prior chunk retrieval for requests that omit the threshold. Evidence: traced the request default through the RAG flow to the vector query.

vector_index=vector_index,
embedding=embedding,
topk=max_items,
vector_dis_threshold=self.wk_input.vector_dis_threshold,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ When a /rag request omits vector_dis_threshold, RAGRequest supplies 0.9 and the flow forwards that value here, so setting VECTOR_DIS_THRESHOLD=2.0 still searches chunks at 0.9. This makes the documented migration escape hatch ineffective for existing API clients. Please let an omitted request threshold resolve to the configured value and add an API-to-store regression test.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed — the omitted case resolved to the configured value in 5d587ef, and f1b9aab adds the API-to-store regression test you asked for.

Root cause of the original defect: RAGRequest defaulted the field to 0.9 and the flow forwarded it verbatim, so VECTOR_DIS_THRESHOLD could not take effect for existing clients. The field is now Optional with None meaning "resolve per consumer".

Validation: test_omitted_request_threshold_keeps_chunk_retrieval_at_configured_default and test_explicit_request_threshold_does_not_change_chunk_retrieval in test_rag_request_defaults.py drive the real hop — RAGRequest -> RAGVectorOnlyFlow.prepare -> VectorQueryNode -> VectorIndexQuery -> chunk store search — and assert the store is searched at CHUNK_DIS_THRESHOLD for both an omitted and an explicit request threshold; test_explicit_request_threshold_still_scopes_keyword_matching pins the request value reaching SemanticIdQuery. The model-level tests above still pin None by default and acceptance of explicit 0.

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: yes. Summary: Omitted thresholds now resolve to CHUNK_DIS_THRESHOLD and VECTOR_DIS_THRESHOLD, but an explicit request vector_dis_threshold also drives chunk retrieval, so API clients that tune keyword matching start losing chunks that the hard-coded 2 kept.

vector_index=vector_index,
embedding=embedding,
topk=max_items,
vector_dis_threshold=wk_input.vector_dis_threshold,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: a /rag request that sends vector_dis_threshold (for example 0.9, the field's previous default) now filters chunks at that value too, so on squared-L2 stores a chunk at cosine 0.5 is dropped where the base kept it. Keep the request field scoped to keyword matching and let chunk retrieval use CHUNK_DIS_THRESHOLD (or a separate request field).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in f1b9aab — taking the CHUNK_DIS_THRESHOLD option you gave, no separate request field.

Root cause: VectorQueryNode.node_init forwarded the request's vector_dis_threshold into VectorIndexQuery, where an explicit value overrode CHUNK_DIS_THRESHOLD, so an explicit 0.9 pruned chunks as well as keyword matching.

Structural fix: the node no longer passes a threshold — chunk retrieval always prunes at CHUNK_DIS_THRESHOLD — and the operator parameter is renamed chunk_dis_threshold so the coupling cannot return through an ambiguous name. SemanticIdQueryNode still resolves the request field (falling back to VECTOR_DIS_THRESHOLD) unchanged.

Validation: red-green test_node_init_keeps_request_threshold_out_of_chunk_retrieval (request 1.2 no longer reaches the operator; red before the fix pins the forward), plus API-to-store chain tests in test_rag_request_defaults.py that drive request -> flow prepare -> node -> real VectorIndexQuery -> chunk store search: an omitted and an explicit request threshold both search chunks at CHUNK_DIS_THRESHOLD, while the explicit value still reaches SemanticIdQuery. Full suite 1310 passed / 2 known pre-existing failures; ty unchanged (2 pre-existing).

@lplalbert

Copy link
Copy Markdown
Contributor Author

Thanks for the careful review — both points land, and the fix is pushed (1da8b0d).

Root cause: the PR routed chunk retrieval through VECTOR_DIS_THRESHOLD and defaulted the
request field to 0.9, so (a) requests that omit the threshold silently switched chunk
pruning from 2.0 to 0.9 and lost chunks without opting in, and (b) the suggested
VECTOR_DIS_THRESHOLD=2.0 escape hatch also loosened keyword-to-vertex matching in
SemanticIdQuery. On squared-L2 stores (FaissVectorIndex, Milvus L2) the distances are
squared anyway, so a cosine-scale 0.9 there drops even more chunks — the historical 2.0
cutoff is what those index paths were effectively tuned against.

Structural fix:

  • Chunk retrieval now has its own knob: CHUNK_DIS_THRESHOLD (default 2.0 = the historical
    hard-coded value) used by VectorIndexQuery when a request omits the threshold — the
    default chunk behavior is unchanged.
  • VECTOR_DIS_THRESHOLD (0.9) stays dedicated to SemanticIdQuery.
  • vector_dis_threshold is now Optional[float] = None on both request models: omitted →
    each path resolves its own configured default; explicit → per-call override of both.
  • Flows pass explicit values through verbatim, so 0 keeps meaning "exact matches only"
    (previously x or default swallowed it).
  • config.md documents both knobs.

Validation (offline): 453 passed in operators/nodes/api; full suite 1295 passed, 16 skipped,
2 pre-existing Windows failures (POSIX mode bits in test_external_config.py, unrelated).
ruff clean; ty 269 (main baseline 271 — VectorQueryNode now narrows wk_input through the
repo's cast(WkFlowInput, ...) idiom instead of adding another None-union deref).

@imbajin imbajin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: yes. Summary: An explicit zero threshold filters out exact matches. Evidence: traced the request threshold to the vector store distance comparison.

prepared_input.vector_dis_threshold = vector_dis_threshold or huge_settings.vector_dis_threshold
# Keep 0.0 meaning "exact matches only"; each consumer resolves its own
# configured default (VECTOR_DIS_THRESHOLD / CHUNK_DIS_THRESHOLD).
prepared_input.vector_dis_threshold = vector_dis_threshold

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ An explicit 0 is now forwarded as an exact-match threshold, but the vector stores filter with distance < dis_threshold (for example, FaissVectorIndex.search), so even a zero-distance result is discarded. This can leave both chunk and vertex retrieval empty for an exact match. Please make the zero boundary include exact matches across the affected stores and add a store-level regression test.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in b7fef91. Root cause: the store filter was a strict distance < dis_threshold, so a forwarded 0 dropped even zero-distance results. The threshold is now an inclusive bound across the affected stores (Faiss, Milvus, Qdrant): a hit is kept when distance <= dis_threshold, so 0 keeps exact matches only. VectorStoreBase.search documents the inclusive contract.

Store-level regression tests cover the zero boundary and an exact hit at the threshold distance for all three backends (test_faiss_vector_index.py::TestThresholdSemantics, test_optional_vector_clients.py::test_qdrant_threshold_semantics_include_exact_matches, test_optional_vector_clients.py::test_milvus_threshold_semantics_include_exact_matches); this coverage also retires the cross-backend threshold-semantics FIXME in test_faiss_vector_index.py.

Validation: src/tests/indices/ src/tests/operators/index_op/ src/tests/api/test_rag_request_defaults.py — 84 passed, 1 skipped; ruff clean on touched files.

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: yes. Summary: An explicit request vector_dis_threshold still drives chunk retrieval, so clients that tune keyword matching lose chunks the hard-coded 2 kept. The inclusive bound also misses exact matches on Qdrant, where float32 cosine scores for identical vectors can fall just below 1.0.

The earlier review comments below still apply at b7fef91; this head does not fix them.

  • Important: a /rag request that sends vector_dis_threshold (for example 0.9, the field's previous default) now filters chunks at that value too, so on squared-L2 stores a chunk at cosine 0.5 is dropped where the base kept it. Keep the request field scoped to keyword matching and let chunk retrieval use CHUNK_DIS_THRESHOLD (or a separate request field). (#412 (comment))

for hit in search_result:
distance = 1.0 - hit.score
if distance < dis_threshold:
if distance <= dis_threshold:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: Qdrant computes cosine scores in float32, so an identical vector can score just below 1.0 and 1.0 - hit.score lands above 0, dropping the exact match an explicit 0 threshold should keep. Compare against a small tolerance, such as distance <= dis_threshold + 1e-6.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch - adopted in cc6d391: the Qdrant filter now compares distance <= dis_threshold + _DISTANCE_TOLERANCE (_DISTANCE_TOLERANCE = 1e-6, named so the reason is visible at the use site: cosine scores are float32, so an exact match can round to 0.99999994 and compute a tiny positive distance instead of 0.0).

Scoped to Qdrant only - Faiss and Milvus return exact 0.0 for identical inputs, so they keep the strict inclusive comparison.

Regression test test_qdrant_threshold_tolerates_float32_score_noise pins both ends: a hit at score 0.99999994 survives dis_threshold=0, while hits at distance 1e-5 (outside the tolerance) and 0.5 are still dropped.

Validation: SKIP_EXTERNAL_SERVICES=true uv run pytest hugegraph-llm/src/tests/indices/ -> 24 passed, 1 skipped (test fails without the tolerance); ruff clean.

@bitflicker64

Copy link
Copy Markdown
Contributor

The earlier review comments below still apply at cc6d391; this head does not fix them.

@imbajin imbajin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Score: 6.5/10 · Confidence: high

Blocking: yes

Summary

Valid Milvus text chunks can be silently discarded, and the request threshold still changes existing chunk retrieval.

Evidence

Traced raw chunk indexing through Milvus JSON decoding and the new result filter; verified the explicit request threshold reaches chunk search.

Validation notes

Static source review only; no live vector database or provider integration was run.

if isinstance(result, str):
checked.append(result)
else:
log.warning("Filter out vector result with unexpected format: %s", type(result).__name__)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Preserve JSON-shaped text chunks from Milvus

Milvus stores string chunks unchanged but decodes every retrieved property with json.loads, so a valid chunk such as 123, true, or a JSON object arrives here as a number, boolean, or dictionary and is discarded. Previously this could fail at the join; this change instead allows retrieval to complete with missing context. Please preserve the original chunk text through the Milvus round trip (including already indexed data), and cover JSON-shaped chunks in a retrieval test.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 129cc48.

Root cause: the Milvus store decoded every retrieved property VARCHAR with a json.loads heuristic on the way out, so chunk text that happens to parse as JSON (123, true, {"answer": 42}) came back as a number/bool/dict, and the format check at this call site dropped the non-strings — the silent "missing context" you describe.

Structural fix: at the producing boundary — search() and get_all_properties() now return the stored text verbatim (the encode side keeps one rule: strings stored as-is, other values as JSON text), and the decode step is deleted, so already-indexed rows read back as their exact stored text. get_all_properties() also stops filtering property != "" server-side; an empty string is a valid property value.

Validation: red-green retrieval tests drive the real VectorIndexQuery over a Milvus collection double — test_milvus_retrieval_keeps_json_shaped_chunks_for_chunk_query (JSON-shaped chunks reach context["vector_result"] unchanged; red before the fix keeps only ["plain chunk"]), plus test_milvus_search_returns_json_shaped_chunk_text_unchanged and test_milvus_get_all_properties_round_trips_stored_text_including_empty. Full suite 1310 passed, 12 skipped, 2 failed (the known pre-existing Windows mode-bit pair in test_external_config); ty unchanged at 2 pre-existing diagnostics. The format check here remains as a pure type guard — every backend now hands it strings.

Scope note: non-string add() values keep their existing storage form (JSON text) and come back as that text; an envelope that restored original types could not distinguish already-indexed JSON-shaped strings. The per-backend contract is documented on VectorStoreBase in #414.

lplalbert and others added 6 commits November 16, 2026 02:44
…dexQuery

VectorIndexQuery hard-coded dis_threshold=2, dropping the documented
VECTOR_DIS_THRESHOLD knob (default 0.9) that already governs SemanticIdQuery
and is exposed on the RAG API, and stored search results without format
checks, so a non-string property crashed the debug join and the downstream
rerank.

- accept vector_dis_threshold (None falls back to VECTOR_DIS_THRESHOLD) and
  forward it to VectorStoreBase.search
- pass wk_input.vector_dis_threshold through from VectorQueryNode
- filter non-string results with a warning before they reach joins/rerank
- cover operator pass-through, settings default, result filtering and the
  flow-to-operator contract in tests (replaces the test FIXME)

Note: chunk retrieval now honors the configured threshold instead of the
hard-coded 2.0; set VECTOR_DIS_THRESHOLD=2.0 to keep the previous loose
filtering.

Co-Authored-By: Claude Code <noreply@anthropic.com>
- add CHUNK_DIS_THRESHOLD (default 2.0) as the chunk retrieval pruning
  knob in VectorIndexQuery; VECTOR_DIS_THRESHOLD (0.9) stays dedicated to
  SemanticIdQuery keyword-to-vertex matching
- make request vector_dis_threshold optional: omitted requests resolve
  each path's configured default instead of a frozen 0.9
- pass explicit thresholds through the RAG flows verbatim so 0.0 keeps
  meaning "exact matches only" instead of silently falling back
- narrow VectorQueryNode wk_input reads through cast(WkFlowInput, ...)
  to hold the ty baseline (271 -> 269)
- cover falsy thresholds, request defaults, and settings fallbacks

Co-Authored-By: Claude Code <noreply@anthropic.com>
A hit is now kept when its distance is at or below the threshold in
Faiss, Milvus and Qdrant, so an explicit 0 threshold keeps exact
matches instead of silently dropping them. VectorStoreBase.search
documents the inclusive contract; regression tests cover the zero and
boundary-distance cases for all three backends and retire the
cross-backend threshold-semantics FIXME.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Qdrant cosine scores are float32, so an exact match can round to a
score slightly below 1.0 (e.g. 0.99999994), making its distance a tiny
positive number instead of 0.0 and dropping it at dis_threshold=0.
Compare against dis_threshold + 1e-6 so exact matches survive without
loosening the bound for genuinely distant results. Faiss and Milvus
yield exact 0.0 for identical inputs and keep the strict comparison.

Co-Authored-By: Claude Code <noreply@anthropic.com>
…operties

search() decoded the stored VARCHAR text with a json.loads heuristic, so
JSON-shaped chunk text ("123", "true", '{"answer": 42}') came back as
other types and the chunk format check dropped it as malformed context.
get_all_properties() additionally filtered empty-string properties out
server-side, breaking the add()/get_all_properties() round trip.

Return the stored text verbatim from both paths and query every row.
Non-string add() values keep their documented storage form: JSON text.

Co-Authored-By: Claude Code <noreply@anthropic.com>
VectorQueryNode forwarded the API request field into VectorIndexQuery,
where an explicit value overrode CHUNK_DIS_THRESHOLD for chunk
retrieval. The request field is scoped to keyword-to-vertex matching
(VECTOR_DIS_THRESHOLD via SemanticIdQuery), so chunk retrieval now
always prunes at CHUNK_DIS_THRESHOLD and the operator parameter is
renamed to chunk_dis_threshold to match its only meaning.

Covered by API-to-store chain tests: an omitted request threshold and an
explicit one both search chunks at CHUNK_DIS_THRESHOLD, while the
explicit value still reaches keyword matching.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@lplalbert
lplalbert force-pushed the fix/vector-index-query-dis-threshold branch from cc6d391 to f1b9aab Compare November 15, 2026 19:03
@lplalbert

Copy link
Copy Markdown
Contributor Author

Confirmed unfixed at cc6d391 — pushed f1b9aab for it. I also owe a correction on my earlier note: reading an explicit request value as a per-call override of both chunk retrieval and keyword matching was wrong; the field is scoped to keyword matching.

Root cause: VectorQueryNode forwarded wk_input.vector_dis_threshold into VectorIndexQuery, where the explicit value overrode CHUNK_DIS_THRESHOLD — exactly the 0.9-filters-chunks behavior in r4516553841.

Structural fix: the node no longer forwards the field; chunk retrieval always prunes at CHUNK_DIS_THRESHOLD, and the operator parameter is renamed chunk_dis_threshold so the coupling cannot return through an ambiguous name. No separate request field was added.

Validation: red-green test_node_init_keeps_request_threshold_out_of_chunk_retrieval plus API-to-store chain tests (test_rag_request_defaults.py: request -> flow prepare -> node -> chunk store search at CHUNK_DIS_THRESHOLD for both omitted and explicit thresholds; the explicit value still reaches SemanticIdQuery). Full suite 1310 passed, 12 skipped, 2 known pre-existing failures (Windows mode-bit pair in test_external_config). Also on this head: 129cc48 preserves JSON-shaped chunk text through the Milvus round trip (r4578310176).

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: yes. Summary: Milvus search() drops the json.loads decode, so the gremlin example index returns JSON strings instead of dicts and GremlinGenerateSynthesize._format_examples raises TypeError in Text2Gremlin and in default GraphRAG on Milvus.

# Property strings round-trip verbatim: decoding JSON-shaped
# chunk text ("123", '{"a": 1}') would change its type and
# make downstream consumers drop it as malformed.
ret.append(hit.entity.get("property"))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: the gremlin_examples index stores {"query", "gremlin"} dicts as JSON text, so this returns a str and GremlinGenerateSynthesize._format_examples raises TypeError on example['query'], breaking Text2Gremlin and the GraphRAG gremlin path on Milvus. Decode string hits with json.loads in GremlinExampleIndexQuery._get_match_result and add a Milvus dict round-trip test.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in aeed04e — good catch, this was a regression from 129cc48.

Root cause: the gremlin_examples index stores its {"query", "gremlin"} dicts as JSON text (text-column backend), and GremlinExampleIndexQuery._get_match_result returned whatever the store handed it. The removed store-side decode had been serving this index, so with verbatim stored text the consumer received strings and _format_examples raised TypeError on example['query'].

Structural fix: decode at the boundary that owns the example shape — _get_match_result parses string hits with json.loads, restoring the dict format for Text2Gremlin and the GraphRAG gremlin path while chunk text keeps its verbatim round trip (that half of 129cc48 stays correct for the chunks index).

Validation: red-green — test_get_match_result_decodes_stored_json_text (mock store returns JSON text and an already-decoded dict) and the demanded test_milvus_dict_properties_round_trip_into_gremlin_example_results (dict -> Milvus stored text -> _get_match_result -> the same dict; red before the fix returns the JSON string). Full suite 1312 passed, 12 skipped, 2 known pre-existing failures; ruff clean; ty 0 new. The string round-trip guarantee from your #414 note is now documented beside this implementation in 83ba325.

(results greater than this will be ignored).",
vector_dis_threshold: Optional[float] = Query(
None,
description="Distance threshold override for this request, applied to chunk retrieval and \

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: this description says the field applies to chunk retrieval, but VectorQueryNode no longer forwards it, so chunk retrieval always uses CHUNK_DIS_THRESHOLD. Describe it as the keyword-to-vertex override falling back to VECTOR_DIS_THRESHOLD, here and in GraphRAGRequest.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 2e68185. Both RAGRequest and GraphRAGRequest now describe vector_dis_threshold as the keyword-to-vertex override falling back to VECTOR_DIS_THRESHOLD, and state explicitly that chunk retrieval always prunes at CHUNK_DIS_THRESHOLD and ignores the field.

lplalbert and others added 3 commits November 16, 2026 10:09
Returning Milvus property text verbatim exposed that the gremlin_examples
index stores {"query", "gremlin"} dicts as JSON text: the consumer
received strings and GremlinGenerateSynthesize._format_examples raised
TypeError on example['query'], breaking Text2Gremlin and the GraphRAG
gremlin path on Milvus.

Decode string hits in _get_match_result, where the example shape is
known, so chunk text in other indexes keeps its verbatim round trip.
Covered by a mock-store decode test and a Milvus dict round-trip test.

Co-Authored-By: Claude Code <noreply@anthropic.com>
…ride

The request field description still claimed the value applied to chunk
retrieval, but chunk retrieval always prunes at CHUNK_DIS_THRESHOLD.
Describe the field as the keyword-to-vertex override falling back to
VECTOR_DIS_THRESHOLD in both request models.

Co-Authored-By: Claude Code <noreply@anthropic.com>
search() and get_all_properties() now document that property strings
round-trip verbatim (including JSON-shaped text and empty strings), so
the promise lives with the implementation that establishes it.

Co-Authored-By: Claude Code <noreply@anthropic.com>
lplalbert pushed a commit to lplalbert/hugegraph-ai that referenced this pull request Nov 16, 2026
The string round-trip guarantee does not hold at this head (the Milvus
decode and empty-string filter are fixed in apache#412), so its sentences move
to apache#412 beside the code that establishes it. This contract now documents
the per-backend non-string storage forms and the input/read split only.

Co-Authored-By: Claude Code <noreply@anthropic.com>

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: yes. Summary: Milvus search() now returns numeric vids as their stored JSON text, so fuzzy keyword matches on number-id vertices stop resolving in the subgraph query. The threshold split and the earlier review comments are addressed at this head.

# Property strings round-trip verbatim: decoding JSON-shaped
# chunk text ("123", '{"a": 1}') would change its type and
# make downstream consumers drop it as malformed.
ret.append(hit.entity.get("property"))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: a numeric vid from an AUTOMATIC or CUSTOMIZE_NUMBER label is stored as "123" and now comes back as that string, so GraphQueryNode._subgraph_query sends g.V(['123']), which HugeGraph resolves as a StringId that never matches the LongId vertex. Decode numeric vids on the graph_vids read path, as GremlinExampleIndexQuery does for examples, and add an int vid round-trip test.

@imbajin imbajin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Score: 7.0/10 · Confidence: high

Blocking: yes

Summary

Milvus numeric vertex IDs change type and can miss graph vertices, as identified in the existing review.

Evidence

Inspected the exact-head Milvus storage, semantic index and graph query paths; the existing comment identifies the unhandled ID conversion.

Validation notes

Static review only; no live HugeGraph or Milvus integration was exercised.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants