3.4 KiB
Context
The indexing path now builds embeddings from structured text:
Title: {title}
Path: {breadcrumb}
Content:
{content}
The persisted Milvus content field remains the raw chunk content. This improves semantic recall for section-aware questions, but only after documents are reindexed. Existing vectors were generated from the previous content-only input and cannot reflect the new breadcrumb signal.
The repository already has an offline fixture-based retrieval baseline. That baseline is useful for deterministic regression checks, but it does not prove that the live Milvus/Zilliz collection has been reindexed or that the running service returns breadcrumb-aware results.
Goals / Non-Goals
Goals:
- Provide an explicit post-reindex live acceptance flow.
- Make the reindex prerequisite visible in documentation.
- Add a small script that calls the live retrieval endpoint with representative queries and writes reviewable reports.
- Keep the live flow optional so unit tests and offline evaluation remain service-free.
Non-Goals:
- Do not add a new reindex API in this change.
- Do not automatically mutate live Milvus/Zilliz data from the acceptance script.
- Do not change
lookup_knowledge, VectorStore retrieval, or Milvus schema. - Do not commit environment-specific live results unless they were intentionally captured for interview evidence.
Decisions
Decision 1: Keep Reindex Manual And Explicit
The acceptance flow documents that reindexing must happen before live validation, but it does not perform the reindex itself.
Rationale:
- Reindexing is a data mutation and can be slow or environment-specific.
- The existing project already has indexing paths through upload, document management, and knowledge-base initialization.
- Keeping mutation separate from validation makes failures easier to diagnose.
Alternative considered: add a script that triggers reindex and then validates. This was rejected for now because it would need environment-specific credentials, source selection, and safety controls.
Decision 2: Use HTTP Endpoint Validation
The script calls /api/search/similar instead of invoking Java services directly.
Rationale:
- It validates the same runtime path used in demos.
- It works across SDK, Spring AI, and auto retrieval modes.
- It produces a simple artifact that can be shown in interview material.
Alternative considered: add a Java integration test. This was rejected because live Milvus and Spring Boot availability should remain optional.
Decision 3: Preserve Offline Baseline Separately
The existing fixture-based evaluator remains the deterministic baseline. The new live acceptance flow is a smoke/regression companion, not a replacement.
Rationale:
- Offline reports are stable and CI-friendly.
- Live reports prove environment readiness and post-reindex behavior.
- Keeping both avoids mixing deterministic fixture checks with external-service validation.
Risks / Trade-offs
- [Risk] Live results vary by environment, indexed documents, and retrieval mode. -> Mitigation: report the base URL, query set, result count, top candidates, score labels, and timestamp.
- [Risk] A developer may run live validation before reindexing. -> Mitigation: document the prerequisite clearly and include a report note.
- [Risk] The script could be mistaken for a benchmark. -> Mitigation: position it as acceptance smoke coverage; keep offline baseline for deterministic metrics.