fix(rag): normalize Milvus L2 retrieval scores

[liugy789]

Summary

• Pass the configured metric type to the Milvus SearchReq.
• Normalize L2 distances into higher-is-better scores.
• Apply scoreThreshold after score normalization.
• Add regression tests for score conversion, metric propagation, and thresholding.

Why

Milvus L2 search returns distances where smaller values indicate greater similarity. AgentScope retrieval uses a higher-is-better score contract, so raw L2 distances must be adapted before they are exposed as document scores.

This PR uses 1 / (1 + distance) as an AgentScope-side normalization formula. This formula is not a Milvus-defined conversion.

Validation

• MilvusStoreTest: 65 tests passed.
• RAG simple module: 449 tests passed.
• Spotless check passed.
• git diff --check passed.

References

• Milvus Metric Types
• Milvus Basic Vector Search
• Milvus Java IndexParam API

Fixes #3069

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[dailingtao]

LGTM

[oss-maintainer]

Summary

Right problem, right direction: raw Milvus L2 distances were fed straight into the higher-is-better score contract and then compared against scoreThreshold, so L2 collections filtered essentially backwards. Passing the configured metric to SearchReq and normalizing before thresholding fixes it, with tests for conversion, propagation and ordering. Two compatibility asks: validate configured metric against the existing collection index, and call out the threshold retuning in a changelog.

---

Automated review by github-manager-bot

[oss-maintainer]

Passing metricType explicitly to SearchReq is new behaviour: previously Milvus searched with the metric recorded on the collection index, now it searches with the configured metric. When a store connects to an existing collection whose index metric differs from the builder default (COSINE), this turns a previously-working search into a provider-side error or wrong ranking. Could you validate the configured metric against describeIndex/describeCollection at connect time and fail fast with a message naming both values? The javadoc note alone will be easy to miss for people who configured the store before this change.

[oss-maintainer]

1 / (1 + distance) is a reasonable monotone map into (0, 1], and applying the threshold after normalization is the correct order. This is still a breaking change for anyone who already tuned scoreThreshold against raw L2 distances, and the resulting scores are not comparable with COSINE/IP scores. Worth a changelog entry plus a note in the RAG docs that thresholds must be re-tuned for L2 collections.