bugfix: allow optional embedding dimensions in OpenAITextEmbedding to…

[Asaduddin18]

AgentScope-Java Version

2.0.1-SNAPSHOT

Description

Background: OpenAITextEmbedding always sent a dimensions parameter to the embeddings API and required it to be a positive int. This works for OpenAI's own models (text-embedding-3-small/large), which support matryoshka representation learning, but breaks for OpenAI-API-compatible open-source models (e.g. BAAI/bge-large-zh-v1.5) that don't support this parameter — they return a 400 error when it's included.

Changes:

• Changed the internal dimensions field from int to Integer so it can be left unset (null).
• Added a new constructor overload taking Integer dimensions (null-safe); kept the original int-based constructor for binary compatibility, now delegating to the new one.
• Builder.dimensions(...) is now optional — omitting it no longer throws, and the dimensions request field is simply left off the API call.
• dimensions validation (must be positive) only runs when a value is actually provided.
• getDimensions() falls back to a DEFAULT_DIMENSIONS = 1024 constant when no explicit value was configured, to satisfy the EmbeddingModel interface contract.
• Response dimension-mismatch validation is now skipped when dimensions wasn't explicitly configured.

How to test:

mvn test -pl agentscope-extensions/agentscope-extensions-rag/agentscope-extensions-rag-simple -am -Dtest=OpenAITextEmbeddingTest,OpenAITextEmbeddingEmbedTest

Covers: building without dimensions(), getDimensions() default fallback, embedding calls with the parameter omitted from the request, and validation for both the deprecated int constructor and the new Integer constructor when given non-positive values.

Fixes #1095

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[AgentScopeJavaBot]

🤖 AI Review

Changes OpenAITextEmbedding.dimensions from int to Integer (nullable), making dimensions optional for OpenAI-API-compatible models that reject this parameter. Good backward compatibility. Note: Builder default changed silently from 1536 to null; getDimensions() returns hardcoded 1024 when unset.

[AgentScopeJavaBot]

All previously raised review comments have been addressed.

[oss-maintainer]

Summary

Makes embedding dimensions optional in OpenAITextEmbedding to support models that do not require explicit dimension configuration.

Findings

• [Info] Constructor changes allow null dimensions. Correct.
• [Info] Tests verify both scenarios (with and without dimensions). Good coverage.

Verdict

Useful flexibility for different embedding models. LGTM.

---

Automated review by github-manager