Vector store observations support several key-value pairs, coming from the Spring AI abstractions. Currently, whenever a value is not available (either because not configured by the user or not supported by the vector store provider), span/metrics attributes are generated anyway with value none.
That causes several issues, including an unneeded increase in time series, challenges in alerting/monitoring (especially for integer/double attributes that suddenly are populated with a string), and non-compliance with the OpenTelemetry Semantic Conventions (according to which, attributes should be excluded altogether if there's no value).
This pull request changes the conventions for vector store observations to exclude the generation of span/metrics attributes for optional values which don't have any value.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
Testcontainers 1.20.2 offers `MongoDBAtlasLocalContainer`. Previous
image used during tests was pulling images in every execution. The
new image is cached locally and can be executed offline.
This commit introduces a major overhaul of the advisor system in Spring AI,
improving modularity, type safety, and consistency
Core Changes:
- Replace RequestAdvisor and ResponseAdvisor with CallAroundAdvisor and StreamAroundAdvisor
- Introduce AdvisedRequest and AdvisedResponse classes for better encapsulation
- Deprecate RequestResponseAdvisor in favor of new advisor types
- Remove AdvisorObservableHelper class
Advisor Implementation Updates:
- Update AbstractChatMemoryAdvisor, MessageChatMemoryAdvisor, PromptChatMemoryAdvisor,
QuestionAnswerAdvisor, SafeGuardAroundAdvisor, SimpleLoggerAdvisor, and
VectorStoreChatMemoryAdvisor to implement new advisor interfaces
- Remove CacheAroundAdvisor (functionality likely moved elsewhere)
- Make CallAroundAdvisor and StreamAroundAdvisor extend Ordered interface
Client and Chain Management:
- Modify DefaultChatClient to use new advisor chain approach
- Refactor DefaultAroundAdvisorChain for better ordering and observation
- Implement builder pattern for advisor chain construction in DefaultChatClient
- Separate call and stream advisors in DefaultAroundAdvisorChain
Observation and Context Handling:
- Update observation conventions and context handling in advisors
- Add order field to AdvisorObservationContext
- Modify DefaultAdvisorObservationConvention to include order in high cardinality key values
Testing and Integration:
- Refactor ChatClientAdvisorTests and add new AdvisorsTests
- Update integration tests to reflect new advisor structure
- Enhance AdvisorsTests to verify correct advisor execution order
New Features:
- Generalize the Protect From Blocking functionality across all advisors
- Add (experimental) Re2 advisor to enhance reasoning capabilities of LLMs
- Add disabled Re2 test in OpenAiChatClientIT
Documentation:
- Add Advisors documentation
- Enhance advisors documentation with order explanation and Re2 example
Advisor Ordering:
- Introduce Advisor constants for precedence ordering
- Update AbstractChatMemoryAdvisor to use new precedence constant
- Improve advisor ordering and management in DefaultAroundAdvisorChain.Builder
- Remove redundant reordering logic from DefaultAroundAdvisorChain
These changes aim to provide a more flexible and powerful advisor system,
allowing for easier implementation of complex AI-driven interactions
Co-authored-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
Resolves https://github.com/spring-projects/spring-ai/issues/1199
- Implement configurable maxDocumentBatchSize to prevent insert timeouts
when adding large numbers of documents
- Update PgVectorStore to process document inserts in controlled batches
- Add maxDocumentBatchSize property to PgVectorStoreProperties
- Update PgVectorStoreAutoConfiguration to use the new batching property
- Add tests to verify batching behavior and performance
This change addresses the issue of PgVectorStore inserts timing out due to
large document volumes. By introducing configurable batching, users can now
control the insert process to avoid timeouts while maintaining performance
and reducing memory overhead for large-scale document additions.
Apply batching when adding Documents to the following vector stores:
- Azure vector store
- Cassandra
- MongoDB Atlas
- OpenSearch
- Oracle
- Pinecone
This improves efficiency by processing multiple Documents at once instead of individually, reducing the overhead for each operation.
Related to #1261
Apply batching when adding Documents to the following vector stores:
- Chroma
- ElasticSearch
- Neo4j
- Qdrant
- Redis
- Typesense
- Weaviate
This improves efficiency by processing multiple Documents at once instead of individually, reducing the overhead for each operation.
Related to #1261
- Precompute all embeddings using a BatchingStrategy before inserting into the vector store
This optimization improves efficiency when adding multiple documents
Related to #1261
- Based on the pattern established in other vector store support implementations,
added a builder class as an inner class of the GemfireVectorStoreConfig class which
is also moved as an inner class to GemfireVectorStore.
Based on the original PR: https://github.com/spring-projects/spring-ai/pull/1168
* Consolidate usage of “db.collection.name” attribute to track table name, collection name, index name, document name, or whatever concept a vector database uses to store data. Removed “db.index” that was use sometimes instead of “db.collection.name”. This usage is in line with the OpenTelemetry Semantic Conventions.
* Configure query response content to be included as a “span event” instead of a “span attribute” if the backend system supports that, similar to how we do for the model observations.
* Structure vector store observation attributes in dedicated enums, including one for the Spring AI Kinds to avoid hard-coding the same value in a lot of places. This follows the OpenTelemetry Semantic Conventions as much as possible. Also, adopt Spring usual non-null-by-default strategy as much as possible.
* Align vector store conventions to the chat model ones, and follow alphabetical order for values. This is particularly useful for the convention classes, for which the Micrometer performance of exporting telemetry data improves when key values are added already sorted to the context.
* Fix flaky test in Mistral AI.
* Improve Qdrant integration tests.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
Remove the requirement of MongoDB vector store auto-configuration only after `MongoDataAutoConfiguration`.
This enables the `MongoDBAtlasVectorStoreAutoConfiguration` to properly provide custom Mongo conversions.
In `MongoDBAtlasVectorStoreIT` and `MongoDbVectorStoreObservationIT` tests, properly provision the `MongoTemplate`
with custom conversions as these tests are not relying on auto-configuration.
- When embedding documents, allow batching the documents using some criteria.
- `BatchingStrategy` interface with a `TokenCountBatchingStrategy` implementation that uses
the openai max input token size of 8191 as the default.
- Add a default method in EmbeddingModel to embed document using this new batching strategy.
- Change `MilvusVectorStore` to make use of this new batching API.
- Adding unit tests for `TokenCountBatchingStrategy`.
- Adding openai integration test to call the embed API that uses batching.
Resolves https://github.com/spring-projects/spring-ai/issues/1214
Other vector stores will be updated seperately
PgVectorFilterExpressionConverter was generating incorrect SQL for
IN and NOT IN filters with PostgreSQL JSON data types. This caused
BadSqlGrammarException errors when executing queries.
This change modifies the converter to generate correct SQL syntax
for these operations, ensuring compatibility with PostgreSQL's JSON
handling capabilities.
Why:
- Improves query reliability for PgVector stores
- Enables more complex filtering operations on JSON data
- Eliminates unexpected errors in query execution
Fixes#1179
Implementation:
- Introduce AbstractObservationVectorStore with instrumentation for add, delete, and similaritySearch methods
- Create VectorStoreObservationContext to capture operation details
- Implement DefaultVectorStoreObservationConvention for naming and tagging
- Add VectorStoreObservationDocumentation for defining observation keys
- Create VectorStoreObservationAutoConfiguration for auto-configuring observations
- Add VectorStoreObservationProperties to control optional observation content filters
- Update VectorStore interface with getName() method
- Modify PgVectorStore and SimpleVectorStore to extend AbstractObservationVectorStore
- Add vector_store Spring AI kind
Filters:
- Implement VectorStoreQueryResponseObservationFilter
- Add VectorStoreDeleteRequestContentObservationFilter and VectorStoreAddRequestContentObservationFilter
Enhancements:
- Update PgVectorStoreAutoConfiguration to support observations
- Add observation support to PgVectorStore's Builder
- Add VectorStoreObservationContext.Operation enum with ADD, DELETE, and QUERY options
Tests:
- Add tests for VectorStore context, convention, and filters
- Add VectorStoreObservationAutoConfiguration tests
- Add PgVectorObservationIT
Resolves#1205
* Change default schema initialization of vector stores from `true` to `false.`
Users need to explicitly opt-in for schema initialization by setting the
`initialize-schema` property on the corresponding vector store.
* Update integration tests
* Update docs
Fixes#907
Currently, `RedisVectorStoreAutoConfiguration` creates its own
configuration to connect with Redis. This commit reuse
`RedisAutoConfiguration` from spring boot project. It's limited
to Jedis.
- provides a flexible schema, can be combined with a vector store, and supports time-to-live rows.
- fix initialize-schema docs and so that it actually works.
- move CommonVectorStoreProperties to .vectorstore. package
- add CassandraAutoConfiguration to the AutoConfiguration.imports
In testing the docker mongodb/atlas container doesn't throw an exception when
calling `mongoTemplate.executeCommand({"createSearchIndexes": ...});`. However,
when using the Atlas service it does and throws a `IndexAlreadyExists` exception.
Added error handling for error code 68 or error code name `IndexAlreadyExists`.
See: https://www.mongodb.com/docs/manual/reference/error-codes/Fixes#910
This change allows users to specify custom names, facilitating management of multiple vector databases within a single database instance.
Key changes:
- Implement configurable schema, table, and index names for PgVectorStore
- Add properties to set custom schema and table names
- Introduce optional schema/table & field validation for custom configurations
- Include additional tests for new configurations and existing deployments
Additional improvements:
- Rename properties to schemaName, tableName, and schemaValidation
- Update pgvector documentation with new properties
- Add schema/table name tests to PgVectorStoreAutoConfigurationIT and PgVectorStorePropertiesTests
- Create standalone PgVectorSchemaValidator class for schema/table validation
- Add missing 'CREATE SCHEMA IF NOT EXISTS' when initializeSchema=true
- Remove redundant code and classes
Resolves#747
Co-authored-by: Christian Tzolov <ctzolov@vmware.com>
- Adds spring boot auto-configuration support for GemFireVectorStore
- Adds integration test GemFireVectorStoreAutoConfigurationIT
- Includes gemfire-testcontainers in integration tests
- Adds unit test GemFireVectorStorePropertiesTests
- Refactors GemFireVectorStore.java extracting GemFireVectorStoreConfig.java
- Renames spring-ai-gemfire to spring-ai-gemfire-store
- Adds GemFireConnectionDetails
- Adds GemFireVectorStoreProperties with default values
- Remove gemfire-release-repo maven repository
Co-authored-by: Louis Jacome <louis.jacome@broadcom.com>
Co-authored-by: Jason Huyn <jason.huynh@broadcom.com>
