73 lines
3.4 KiB
Markdown
73 lines
3.4 KiB
Markdown
## Context
|
|
|
|
The indexing path now builds embeddings from structured text:
|
|
|
|
```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.
|