iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To make a retrieval-augmented generation (RAG) pipeline provider-agnostic, define application-owned ports for the capabilities it needs—such as embedding, indexing, retrieval, and answer generation—and put each provider’s SDK, credentials, and response translation in an adapter. The application then depends on its own contracts rather than a particular model or database. This makes change and testing easier when there is a real need for them, but it does not make providers behave identically or remove the work of maintaining adapters.
What hexagonal architecture means for a RAG pipeline
Hexagonal architecture, also called ports and adapters, places application behavior behind boundaries defined by the application itself. A port describes an interaction the application needs. An adapter implements that interaction for a particular technology, translating between the application’s types and the provider’s API.
AWS Prescriptive Guidance describes ports as “technology-agnostic entry points into an application component.” In a RAG system, a use case should ask for operations such as embedding text or retrieving relevant documents, not construct provider SDK requests directly. A hosted service, local model, vector database, or external retriever can then sit behind an adapter, provided it satisfies the port’s contract.
Free tools Windows power users keep installed
One-click scans. No signup required.
Where the boundary sits
Keep workflows and application-owned data types in the core. Keep provider packages, authentication, configuration, network calls, and provider-specific response mapping in adapters. Incoming adapters can expose the application to an HTTP API, command-line interface, queue, or scheduled ingestion job; outgoing adapters connect the core to models and data services.
HTTP / CLI / queue / scheduled ingestion
|
v
Application use cases
IngestDocuments | AnswerQuestion | ReindexCollection
|
Application-owned ports
/ |
Embedder Retriever AnswerGenerator
| | |
provider adapter provider adapter provider adapter
_____________ external systems _____________/The diagram is a dependency guide, not a required component count. A small application may combine responsibilities; the important boundary is that a use case does not depend on a provider’s request or response classes.
Which ports a RAG application may need
Define ports around meaningful external interactions, not around every helper function. A useful starting set depends on the actual pipeline:
- Document input: a
DocumentSourceor ingestion input port that provides source content and stable identifiers. - Transformation: a
DocumentTransformerfor parsing, normalization, or chunking when these stages need replaceable implementations. - Embedding: an
Embedderfor single-text or batch embedding. Make model identity and vector dimension explicit in the application’s data model or configuration. - Index writing: an
IndexWriterfor adding, updating, and deleting indexed content. - Retrieval: a
Retrieverthat returns application-owned documents and source metadata, with filters and retrieval options specified deliberately. - Generation: an
AnswerGeneratorthat accepts the application’s message or prompt representation and returns a typed result. - Optional boundaries: a reranker, clock, or telemetry port when isolation or substitution is materially useful.
Keep application types independent
For example, the core can represent a document using text, a stable ID, and metadata, and represent a retrieval result using that document plus an explicitly defined score and source information. The adapter maps these values to and from provider-specific objects. Do not let a provider response type become the application’s document model by accident.
A composition root—the part of the application that assembles the running system—selects concrete adapters for a deployment or a test. Provider configuration and credentials belong there or in the adapter’s configuration, not in domain rules or use-case code.
How to define contracts without pretending providers are identical
A shared interface reduces direct coupling; it cannot erase differences in capabilities or semantics. Write down what the use case relies on, then make each adapter either meet that contract or report that a capability is unavailable. Avoid a generic interface that silently drops options or claims equivalence where none exists.
Embedding requirements
- Record the embedding model identity and vector dimension expected by an index.
- Specify batch behavior and any relevant request limits in adapter configuration or capability checks.
- Confirm that document and query embeddings use compatible models. A common method signature alone does not establish vector compatibility.
Retrieval requirements
- Define which metadata filters the use case needs and whether the adapter supports them.
- Be explicit about similarity search, hybrid or sparse search, pagination, and deletion semantics.
- Do not compare or normalize scores as if they have the same meaning across retrievers unless that behavior has been established for the implementations in use.
LangChain’s retrieval discussion describes multiple approaches, including similarity search, maximal marginal relevance, metadata filters, graph indexes, and retrievers created outside its vector-store approach. These are different capabilities, not interchangeable details hidden by a single method name.
Generation and operational behavior
- Specify whether a use case requires streaming, structured output, tool calls, or a particular context limit.
- Define how the application handles refusals or safety signals if those affect its behavior.
- Set expectations for timeouts, retries, rate limits, cancellation, idempotency, and error categories. Translate provider errors into application-relevant outcomes in the adapter.
- Account for authentication, data retention, residency, and who operates each system.
When a feature is optional, expose it as an explicit capability or deployment choice. Do not promise universal streaming or structured-output behavior through a contract that cannot express whether an adapter supports it.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →How to test the boundaries and change providers
Use several levels of testing
- Use-case tests: substitute fakes for ports to test application decisions quickly without calling a live provider.
- Adapter contract tests: run the same relevant contract checks against each adapter. Verify document mapping, metadata preservation, expected dimensions, filters, error translation, timeouts, and any streaming or structured-output behavior the application relies on.
- Integration tests: keep a smaller suite that exercises real services and deployment configuration. Fakes and contract tests do not prove that providers produce equivalent retrieval or answer quality.
AWS Prescriptive Guidance identifies independent application testing and mocked dependencies as benefits of the pattern. The practical benefit is isolation of application behavior, not a guarantee that a fake captures every behavior of an external service.
Make a provider change a measured migration
- Add an adapter for the new provider that implements the existing port, or revise the port if the application’s genuine requirements have changed.
- Run the adapter contract tests and confirm required capabilities against the provider’s actual behavior.
- Evaluate retrieval and answer quality using representative queries and source documents before routing production traffic to the new implementation.
- Plan a data migration if the embedding model or vector dimension changes. Existing vectors may need to be re-embedded and the index rebuilt; an adapter cannot make incompatible stored vectors interchangeable.
- Decide how traffic, rollback, and index cutover will work for the deployment. The reviewed sources do not establish a universal zero-downtime migration method or quantify migration cost.
Frameworks and deployment choices
Framework abstractions
LangChain’s architecture documentation describes a three-layer structure: provider-agnostic core abstractions, orchestration, and partner packages that implement shared interfaces. That is one example of separating reusable contracts from integrations. It does not establish that every application needs the framework or that every integration offers identical features. Its separate retrieval discussion dates to March 2023, so treat it as conceptual background and check current APIs before implementing against a framework.
Rank #4
Where RAG infrastructure runs
Google Cloud’s RAG architecture guide, last reviewed September 22, 2025, describes several deployment categories: managed vector search, embeddings alongside operational data in AlloyDB, container-based RAG infrastructure, and a CI/CD architecture. These represent different operating models rather than a universal ranking. Service details can change, so confirm current capabilities before choosing an implementation.
Compare deployment options against the same workload and requirements:
Recommended Free Tools
- Operational control: how much of the model, index, and runtime stack the team can configure and operate.
- Data placement: where source documents, embeddings, prompts, and generated answers are processed and retained.
- Portability: which application contracts and data formats can move, and what would still require provider-specific work.
- Scale and reliability: whether the service supports the expected traffic, availability, and recovery needs.
- Team responsibility: who handles upgrades, monitoring, security, backups, and incident response.
- Platform fit: how the option works with existing data systems and deployment practices.
When the extra architecture is worth it
Ports and adapters are most useful when multiple clients or integrations exist, an external technology is plausibly going to change, or isolated tests materially improve development. They can also make responsibilities clearer when ingestion, retrieval, and generation evolve independently.
A lighter design is often better when there is one stable dependency, little application-specific behavior, and no meaningful replacement or testing requirement. AWS also notes the tradeoffs: adapter code must be maintained, additional layers can add complexity, and they may add latency. Create a boundary where it protects a real use case from infrastructure coupling, not merely because a component could theoretically be replaced.
There is no established universal winner or comparative benchmark for RAG providers in the reviewed material. For a real decision, evaluate the options on the same workload: supported capabilities, retrieval and answer quality, migration and re-indexing effort, latency and reliability, privacy and residency, operating effort, portability, and cost. The result depends on the application’s data and operational constraints.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems
