Key Takeaways

• Build a private Python API foundation using FastAPI, OCI Kubernetes Engine, Terraform, and OCI DevOps.
• Track the serving release through version, commit, and environment metadata, preparing for canary verification.
• Package repeatable containers with pinned dependencies, unique release identifiers, and restricted runtime permissions.
• Use OCI Bastion for temporary administrative access while keeping the cluster and application private.
• Connect source, images, deployment manifests, and delivery permissions ahead of the canary rollout in Part II.

A successful container build is only one part of releasing an application. We also need somewhere to run it, a controlled way to reach it, and a way to identify the version answering our requests.

We built a small Python API and developer portal on Oracle Cloud Infrastructure (OCI), with a private Oracle Kubernetes Engine (OKE) cluster and OCI DevOps delivery services. This post explains the foundation. Part 2 follows a commit through testing, a 10% canary rollout, approval, and production promotion.

Naming note: Resource names such as demo-compartment, demo-production, and demo-canary are illustrative pseudonyms. Actual compartment, region, tenancy, repository, cluster, identity, network-address, and release identifiers are omitted.

Choose a small, private deployment

We placed the resources in a dedicated compartment, represented here as demo-compartment, within one OCI region. A compartment groups resources and provides a scope for access policies. Keeping regional resources together simplifies the demo's connectivity.

Our OKE Basic cluster used one VM.Standard.E4.Flex worker with 1 OCPU and 4 GB RAM, plus a 50 GB boot volume. This was sufficient for our stateless application’s production, candidate, and router pods.

That is a demonstration footprint, not a general sizing rule. The workloads share one worker, so a worker failure affects all of them. Namespace separation does not provide host redundancy.

We kept the Kubernetes API, worker, and application private. OCI Bastion provided temporary administrative access from an allowlisted client address.

Make the application identify itself

We used FastAPI to handle HTTP requests and Uvicorn to run the application server. The same application serves the portal page and API endpoints, keeping the demo to one application image.

The portal describes the delivery path and displays the serving revision. Pipeline execution and approval records remain in OCI DevOps.

EndpointWhat it tells us/The portal is reachable/api/helloThe example API contract behaves correctly/healthzThe application process responds/readyzThe application is ready for traffic/api/releaseWhich version, commit, and environment answered/docsThe API contract can be explored interactively

Liveness and readiness serve different purposes. Repeated liveness failures can cause Kubernetes to restart a container. Readiness failures exclude an unready pod from normal Service traffic.

Our readiness signal follows application startup and shutdown. There is no database or other application dependency to check. If we added one, we would need to reconsider the readiness contract.

Release metadata becomes especially useful when two versions run simultaneously. Both may return HTTP 200, but only one is the candidate. The release endpoint reports version, commit, and environment, allowing us to attribute each response without exposing credentials.

The image records the source and version; deployment configuration supplies the environment. This creates a traceable connection from source to the request we observe.

Package a repeatable container

A container image packages the application, runtime, and dependencies. A container is a running instance of that image. Kubernetes runs containers inside pods.

Our Dockerfile starts with a digest-pinned Python 3.12 base image and installs dependencies with package-hash verification. It copies in the application, selects a non-root user, and starts Uvicorn on port 8080.

Pinning versions and hashes controls what enters the build. It also means updates must be deliberate: a pinned dependency does not update itself when a fix becomes available.

Each build creates a version using this structure:

<source-commit-prefix>-<generated-build-suffix>

The version connects the image tag, manifest artifact, and application metadata. Separate builds receive distinct identifiers, and deployment avoids latest.

We verified execution with a read-only root filesystem, dropped Linux capabilities, and no privilege escalation. These restrictions reduce what the process can change and are also reflected in the OKE workload configuration.

A tag names an image reference; a digest identifies image content. We later compared the running production digest with OCIR metadata. This provided evidence beyond the application’s own version string.

The container repository did not accept enforced immutability in this exercise. We used unique tags and restricted writers; immutable versions were enforced for the separate manifest repository.

Build the private foundation with Terraform

Terraform describes both the infrastructure and delivery services. A plan previews proposed changes, an apply carries them out, and later plans reveal differences between configuration and deployed resources.

We separated the network and OKE configuration from the DevOps configuration so their responsibilities remained clear.

The private network used an isolated Virtual Cloud Network (VCN), with subnets for the Kubernetes API, workers, and access resources. Outbound connectivity came from two gateways:

ComponentRoleNAT gatewayAllows private resources to initiate internet connections without public worker addressesService gatewayProvides access to supported OCI services through the OCI service network

Network rules constrain those paths. Outbound connectivity supports image retrieval and service communication without publishing the application for inbound internet traffic.

OKE manages the Kubernetes control plane, while the worker supplies CPU and memory for pods. We organized workloads into namespaces represented here as demo-production, demo-canary, and demo-router. These names will also appear in the release discussion.

Reach OKE through OCI Bastion

The private Kubernetes API cannot be reached directly from a laptop across the public internet. We created a time-limited OCI Bastion session restricted to one allowlisted client address.

An SSH tunnel forwarded a laptop port to the private Kubernetes API. Through that connection, kubectl port-forward forwarded a second local port to the router Service.

Laptop browser
      ↓ local forwarded port
kubectl port-forward
      ↓ API connection through Bastion
Private OKE router Service
      ↓
Application Service and pod

The browser used localhost, but the application ran in OCI. A dedicated kubeconfig kept the connection separate from existing Kubernetes contexts, and API certificate verification remained enabled.

Access requires an active Bastion session and forwarding processes. This is a temporary administrative access path rather than a permanent application URL.

Connect the OCI delivery services

The delivery foundation gives each artifact and operation a home:

OCI resourceResponsibilityDevOps project and Code RepositoryGroup delivery resources and store sourceManaged build pipelineTest source and build release artifactsPrivate OCI Container Registry (OCIR)Store application imagesGeneric Artifact repositoryStore versioned deployment manifestsOKE deployment environmentIdentify the target cluster and connectivityBaseline and canary pipelinesEstablish production and release later candidates

The image contains the application; the manifest tells Kubernetes how to run it. It describes the image reference, replicas, probes, security settings, and routing resources. Delivering both lets promotion consume the artifact evaluated during the canary.

OCI dynamic groups identify authorized pipeline resources, and IAM policies grant their required access. Image pulling uses a separate auth-token-only identity with read access restricted to the application repository. Kubernetes pull secrets provide that credential in both application namespaces, outside the image, source control, and Terraform state.

The foundation now connects identifiable application code, a versioned image, private compute, controlled access, and delivery permissions. The next step is to prove that a source change can move through all of them.

Continue to part 2: Release through an OCI DevOps canary

FAQs

What does Part I cover?

Part I establishes the Python application, container image, private OKE infrastructure, administrative access, and OCI delivery services. Part II follows a source change through canary deployment, approval, and production promotion.

Is this architecture production-ready?

It is a demonstration foundation. All workloads share one worker, so a worker failure affects the application and router. Production use requires additional resilience, capacity planning, and operational validation.

How do I access the private application?

A time-limited OCI Bastion session provides an SSH tunnel to the private Kubernetes API. From there, kubectl port-forward makes the router Service accessible through localhost while the application remains in OCI.

Why does the application expose release metadata?

Successful HTTP responses do not identify which version served them. The release endpoint reports the version, commit, and environment so requests can be attributed to the baseline or candidate during a canary rollout.

How are application images and deployment manifests different?

The image contains the application, runtime, and dependencies. The manifest defines how Kubernetes runs it, including replicas, probes, security settings, and routing. Versioning both supports promotion of the release evaluated during the canary.

Building a Canary Release Pipeline with OCI DevOps (Part I) was originally published in Oracle Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Key Takeaways

• Build a commit-triggered release pipeline with OCI DevOps: test, package, publish artifacts, and deploy a canary to private OKE.
• Verify which release actually serves requests; healthy pods and a configured traffic weight do not prove the traffic split works.
• Evaluate the candidate with 10% of traffic, then approve promotion using the same release artifacts without rebuilding.
• Retain known-good artifacts for recovery. Deployment-stage rollback does not detect every application regression.

A delivery pipeline becomes useful when we can follow a source change into a running application, check its behavior, and control its promotion. A green build is a starting point; the serving revision and traffic path provide the next evidence.

In part 1, we built a Python API, packaged it, and established private OKE infrastructure with OCI delivery services. Here we follow the release: baseline deployment, commit-triggered build, 10% canary, approval, and production verification.

Naming note: Namespace names such as demo-production and demo-canary are pseudonyms. Actual environment names, locations, network addresses, and release identifiers are omitted. Results describe the exercise verified on October 4, 2026, rather than current cloud health.

Establish production before introducing a candidate

A canary rollout needs a working production version to receive most requests. We first ran the managed build with automatic canary delivery disabled, then deployed its artifacts through the separate baseline pipeline into demo-production.

Several Kubernetes objects work together:

ObjectResponsibilityDeploymentMaintains application pods and coordinates updatesPodRuns the application containerServiceGives ready pods a stable destinationIngressDescribes HTTP routing rulesRouterImplements those rules and forwards requests.

An Ingress needs a controller to implement its rules. A Service remains stable as individual pods are replaced and their addresses change.

The private demo runs one application replica per application namespace. Startup, liveness, and readiness probes check the application, and the Service selects ready pods.

Through the private router, we verified health, readiness, the example API response, and the expected release identity. This established a known working baseline before we enabled the complete commit-triggered path.

Turn a source push into a release

We enabled the trigger for pushes to main in OCI Code Repository and the build stage that starts canary delivery.

The resulting path connected source, artifacts, and deployment:

Push to main
↓
Test the API
↓
Build and smoke-test the container
↓
Publish image and manifest
↓
Deploy candidate to OKE
↓
Shift 10 percent of traffic
↓
Wait for approval
↓
Promote the tested release

The build specification directed the runner to:

1. Install hash-verified dependencies and run API tests.
2. Create a unique release version and build the amd64 image.
3. Start the image with the intended runtime restrictions.
4. Run smoke checks and verify the reported version.
5. Render a manifest containing the release’s image reference and metadata.

OCI pipeline stages then delivered the image to OCIR, delivered the manifest to Artifact Registry, and triggered the deployment pipeline with that version. The verified source push started this process automatically, and every build stage succeeded.

This connects continuous integration with continuous delivery. Tests and packaging happen automatically, while production promotion retains an approval point.

Use native OCI DevOps canary stages

The deployment pipeline has four stages:

StageBehaviorCandidate deploymentApplies the candidate into demo-canaryTraffic shiftAssigns 10% of normal traffic to itApprovalWaits for one recorded approvalProduction deploymentApplies the evaluated release into demo-production

The established version continues serving most requests while the candidate is checked. The configured traffic-shift batch delay is not an automated error-rate or latency gate; observation remains necessary.

OCI manages NGINX-style canary annotations. Our private router used Traefik v3.7.13’s NGINX compatibility provider to interpret them. This integration needed verification with live requests.

Diagnose the traffic path before approving

Our first sample revealed a mismatch: the candidate was healthy and its ingress showed a 10% weight, yet every sampled request reached the baseline.

The annotation described the desired behavior. The release endpoint revealed the behavior actually occurring.

Router logs and its implementation showed the cause: this provider matches primary and canary ingress rules within the same namespace. Our initial cross-namespace arrangement did not meet that requirement.

We changed the routing layout while preserving separate application namespaces:

Router watches demo-canary
    │
    ├── Primary ingress
    │       ↓
    │   ExternalName Service alias
    │       ↓
    │   Production Service in demo-production
    │
    └── Candidate ingress
            ↓
        Candidate Service in demo-canary

An ExternalName Service supplies a DNS alias. Here it points to the production Service’s internal Kubernetes name. It does not expose a public endpoint or move production pods.

The matching ingress rules now reside together in demo-canary, while OCI manages the candidate ingress and traffic weight. The router's workload permissions are scoped to that watched namespace.

This is why ingress compatibility must be tested beyond checking that deployment resources exist. Controller matching rules can determine whether the configured split takes effect.

Evaluate the candidate using release identity

After correcting the route, we checked candidate health, readiness, API behavior, release identity, and updated portal content. We then sampled the router’s release endpoint:

Response before approvalCountCandidate20Baseline180HTTP errors0Total requests200

The observed split matched the configured 10% share. Future samples need not divide exactly the same way.

We also verified that the redirect-to-canary: always header selected the candidate, allowing deliberate checks through the router without waiting for normal traffic selection.

Counting successful responses alone would have missed the original problem. Identifying which revision answered demonstrated that the candidate was actually receiving traffic.

Approve and promote without rebuilding

After the checks passed, we recorded approval in OCI DevOps with the verification reason. OCI reset normal candidate traffic to zero during the transition and continued to production deployment.

The production stage consumed the delivered release manifest. No new application build occurred between canary evaluation and promotion.

We verified the resulting production workload through the private router:

CheckRecorded resultAll four deployment stagesSucceededProduction podReady, with zero restarts at verificationHealth and readinessPassedPost-promotion sample50 of 50 requests served the new production releaseHTTP errors in that sample0Running image digestMatched OCIR metadata

The digest comparison supplemented the application-reported version with a check of the running image content.

Keep recovery and future delivery ready

The production stage has automatic rollback configured for deployment-stage failure. Retained baseline artifacts also allow a known-good release to be redeployed without rebuilding.

These controls have limits. A ready application can contain a business-logic defect. This demo has no automated error-rate or latency analysis gate, and stage rollback cannot detect every regression after a successful deployment. Its traffic samples demonstrate functionality rather than production capacity. The single worker also provides no host redundancy.

For a later regression, the recovery path is to remove candidate traffic and redeploy a retained known-good release. Deployment runs should not overlap.

We saved the routing fix and verification record, briefly pausing the trigger for that audit commit. After restoring it, we checked that the trigger was active and Terraform reported no infrastructure drift.

The verified recurring workflow is edit → commit → push → OCI build and artifact delivery → private OKE canary → review → approval → production verification. The key operational habit is to check the revision actually serving requests before deciding a release is ready to promote.

FAQs

What do I need before following Part II?

Part I establishes the Python API, container packaging, private OKE infrastructure, and OCI delivery services. A working production baseline is required before introducing the canary.

Does a 10% canary weight guarantee exactly 10% of requests?

No. Individual samples can vary. Check the release identity returned by each request to confirm that both versions receive traffic and the observed split is consistent with the configured weight.

Why did the ingress routing need adjustment?

The Traefik NGINX compatibility provider used in this exercise matched primary and canary ingress rules within the same namespace. An ExternalName Service alias allowed those rules to sit together while the application workloads remained in separate namespaces.

Is the application rebuilt after approval?

No. The production stage uses the release manifest and image already evaluated during the canary phase.

What happens if a release fails?

Automatic rollback is configured for production deployment-stage failure. For a regression discovered after successful deployment, the recovery path is to remove candidate traffic and redeploy retained known-good artifacts. This demo does not include automated error-rate or latency gates.

Read part 1: Build the private OCI foundation for the application and infrastructure design.

Building a Canary Release Pipeline with OCI DevOps (Part II) was originally published in Oracle Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

By Kailas Jawadekar

A collection of documents can hold valuable knowledge while still being difficult to use. Finding an answer may require opening several files, searching for related terms, and reconciling different versions. We built a Document Knowledge Base to make that content searchable and reusable through natural-language questions, generated drafts, and document comparisons.

The Document Knowledge Base combines Oracle APEX, PL/SQL, Oracle AI Database vector storage, and AI inference. Its core workflow is independent of the subject matter: organize a document collection, retrieve relevant passages, and use them to answer questions or create new content. Support articles, developer guides, operational runbooks, and product documentation are all examples of collections suited to this pattern.

Key takeaways

• Ingest DOCX documents into stored files, metadata, text chunks, and embeddings.
• Use Oracle AI Vector Search and RAG to retrieve evidence for each question.
• Ask for source-grounded answers with filenames and headings to support review.
• Generate editable content from retrieved passages and prompt templates.
• Compare selected documents within a bounded context; check coverage before interpreting omissions.

Review generated results: tables, long passages, missing embeddings, or limited retrieval can leave evidence out. Check answers, drafts, and comparisons against the originals.

Implementation scope

Document Knowledge Base is a simple internal project, not a production deployment. It demonstrates a reusable workflow for finding answers, drafting content, and comparing documents. The collection supplies the subject matter: support guidance, developer documentation, operational procedures, onboarding material, or product knowledge. These broader examples illustrate how the pattern can be adapted; each needs suitable documents, prompts, and coverage checks.

What users can do

The Document Knowledge Base organizes work around three capabilities:

• Ask a question. Semantic search retrieves relevant passages and generates an answer with source references. For a support collection, a question might be “How do I troubleshoot a connection timeout?”
• Create a draft. Retrieved content and template instructions guide an output such as a summary, knowledge article, or response draft. The document collection and prompt determine the subject and format.
• Compare documents. A selected document and baseline provide the evidence for a structured comparison. In a documentation collection, the task might be to summarize changes between two versions.

The current uploader adds DOCX files and metadata. Administration views show document coverage, ingestion status, and missing embeddings.

Use cases for a Document Knowledge Base

The collection and task give the knowledge base its purpose. These examples illustrate applications of the same architecture; each requires suitable source content and prompts.

How the architecture works

Oracle APEX supplies the browser interface, forms, and reports. PL/SQL packages extract text, retrieve passages, assemble prompts, and call the AI service. Oracle AI Database provides native vector storage and AI Vector Search alongside relational data. In this implementation, the schema stores original DOCX BLOBs, filenames, dates, hashes, processing status, extracted text, ordered chunks, and embeddings. It also stores search questions and query vectors, generated answers, reusable prompt templates, and assembled prompts and outputs for generated reports and comparisons. The answer package stores answer text, but does not persist its assembled prompt.

Keeping these records in Oracle AI Database lets SQL join evidence and metadata directly, apply category filters, and retrieve saved generation prompts and outputs without synchronizing a separate vector store. This makes the workflow easier to inspect and maintain; it does not by itself guarantee complete extraction or accurate answers.

The application has two main flows:

Document → Extract text → Split into chunks → Create embeddings → Store
Question → Create embedding → Find relevant chunks → Generate answer

This is retrieval augmented generation, or RAG. The model receives selected source passages with each request; we do not train it on the uploaded documents. Keeping vectors alongside relational data lets SQL combine semantic ranking with metadata filters and explicit document selection.

Our AI wrapper is configured for OCI Generative AI endpoints using OpenAI-compatible embedding and chat request formats. Endpoint URLs and model identifiers are configuration values. API secrets belong in APEX Web Credentials and are referenced by the REST call, keeping them out of application code. The checked-in endpoint defaults and model placeholders are setup values, not proof that those combinations are currently supported. Confirm both embedding and chat access in the target environment using the service’s current documentation.

Prerequisites and setup

• Oracle APEX and database support. Use an APEX workspace and parsing schema on an Oracle Database environment that supports VECTOR, TO_VECTOR, and VECTOR_DISTANCE. Verify the installed APEX and database versions; the source does not establish a tested minimum APEX release. The custom packages use APEX_ZIP, APEX_JSON, and APEX_WEB_SERVICE.
• OCI Generative AI access. Configure reachable HTTPS embedding and chat endpoints, authorized model IDs, regional availability, and the required service permissions. Set EMBEDDINGS_URL, EMBEDDING_MODEL, CHAT_URL, and CHAT_MODEL. Test both calls; an OpenAI-compatible chat endpoint does not automatically imply compatible embedding support. The current vector columns and conversion expect 1,536 dimensions, so check the embedding-dimension diagnostic before ingestion.
• APEX Web Credentials. For the project’s bearer-token setup, create an HTTP Header credential with header Authorization and secret value Bearer <API key>, restricted with Valid for URLs to the intended service prefixes. Set WEB_CREDENTIAL_STATIC_ID to that credential’s Static ID. The later project build instructions use credentials-for-standards-ai, while the original seed uses openai-api-key; match the active workspace credential rather than copying either blindly. Configure outbound network access as required by the database environment.
• Schema, pages, and a small DOCX trial. Install the schema and ingestion, AI, search, answer, template, report, and comparison packages, check compilation, and connect the APEX page processes. Start with a representative DOCX and inspect extracted text, chunks, and embeddings before testing answers. The supplied source is not a complete, verified one-click APEX deployment. The current uploader is DOCX-only; PDF, HTML, Markdown, and images need additional parsers.

See Oracle’s Web Credentials guidance and OCI Generative AI API key and endpoint documentation for the supported authentication and service configuration.

Turning documents into searchable content

When a user uploads a DOCX file, the application retains the original file and calculates a SHA-256 hash to detect an identical upload. It uses APEX_ZIP and XMLTABLE to extract body paragraphs, detects headings, and groups text into chunks of approximately 5,000 characters. Each chunk retains its heading and connection to the source document.

Extraction limitation: the XPath reads direct body paragraphs, not paragraphs inside table cells. The helper takes at most 200 characters per XML text run and caps the assembled paragraph at 3,000 bytes. Long passages can therefore be incomplete before chunking; the original DOCX remains the reference for checking coverage. Chunks have no overlap.

The application creates an embedding for each chunk and stores it as VECTOR(1536, FLOAT32). An embedding is a list of numbers representing the text in a form that supports similarity comparisons. Related passages can be close together even when they use different words. For example, “unable to sign in” may match a passage about “authentication failures.”

The embedding function sends text to the configured model, then converts the returned JSON array into an Oracle vector. This excerpt shows the conversion inside our PL/SQL package:

l_response := embedding_response(p_text);
l_embedding_json := json_query(
  l_response, '$.data[0].embedding' returning clob);

select to_vector(l_embedding_json, 1536, float32)
  into l_vector
  from dual;

embedding_response builds the JSON request with the configured embedding model and input text. Document chunks and questions use the same embedding model so their vectors can be compared.

Finding evidence and generating an answer

For each search, we embed the question once and store its vector. SQL ranks document chunks by cosine distance: a smaller distance means greater semantic similarity. The simplified query below shows the core operation using generic knowledge-base table names. Metadata filters can narrow the candidate documents before ranking.

select c.chunk_id, c.heading, c.chunk_text,
       vector_distance(c.embedding,
                       q.query_embedding, cosine) distance
  from kb_doc_chunks c
  join kb_search_queries q on q.search_id = :search_id
 where c.embedding is not null
 order by distance
 fetch first :top_n rows only;

We assemble the selected passages, filenames, headings, and document dates into a prompt. The instructions ask the model to answer the specific question, cite its sources, and say when the supplied material is insufficient. A shared function handles generation:

l_output := kb_ai_pkg.generate_text(
  p_system_prompt =>
    'Ground every claim in provided source material.',
  p_prompt => l_prompt
);

Inside this function, APEX_JSON constructs the chat request and APEX_WEB_SERVICE.MAKE_REST_REQUEST sends it using the configured Web Credential. The response text is extracted from choices[0].message.content and displayed in APEX.

Reusing the evidence for content and comparisons

Content generation adds a topic, output type, and template instructions to the retrieved context. A template defines the audience, structure, and tone while the source passages supply the evidence. Our implementation saves the assembled prompt and generated text and offers a Markdown download.

Document comparison answers a different question: “What changed between these two documents?” Users select a current document and a baseline, then generate a structured comparison with source references. The screenshot shows the current document and baseline selectors, an optional category filter, and the comparison action.

Unlike semantic search, this workflow takes a bounded set of chunks from each selected document in document order. The prompt labels the two sets as current and baseline and asks for supported changes. The comparison defaults to the first 10 embedded chunks per document, with a maximum of 15, subject to the optional category filter. Because context is bounded, an omitted item is not automatically evidence that it was resolved.

The reusable pieces are document storage, extraction, chunking, embeddings, retrieval, and generation. The domain determines the metadata, filters, and prompts. A support repository might filter by product and version; developer documentation might use API, language, and release. Adapting the application also requires parsers for the source formats and access controls appropriate to the collection. Our current uploader handles DOCX files.

Answer quality depends on the evidence supplied. Our current extractor focuses on body paragraphs, so table content and long passages need attention when assessing coverage. Similarity scores do not establish factual accuracy or freshness, and generated answers still need review against their sources.

The Document Knowledge Base brings these pieces into one workflow: add documents, ask questions, create drafts, and compare sources. Keeping documents, metadata, vectors, reusable prompts, and generated artifacts together in Oracle Database supports that workflow with familiar joins and filters. The next step is to validate extraction and retrieval against representative documents, then review generated outputs against their sources before broader use.

The images show the live Document Knowledge Base application. Code snippets are simplified examples using generic kb_ names; they are not standalone installation scripts.

Further reading: Oracle APEX web service API and Oracle vector distance functions.

Frequently asked questions

What is this app for?

Document Knowledge Base makes a DOCX collection searchable and reusable through questions, generated drafts, and selected-document comparisons. For example, a support team could retrieve troubleshooting guidance, a developer team could draft an API summary, or an onboarding team could help employees find procedures. These uses depend on the documents and prompts supplied.

Which file types are supported?

The current uploader and extractor handle DOCX. They do not implement PDF, HTML, Markdown, scanned images, or complete DOCX table extraction. Adding another format requires a parser and coverage validation.

What does RAG do here?

Retrieval augmented generation embeds a question, ranks stored chunks by semantic similarity, and supplies selected passages to the model as context. Instructions request source-grounded answers and source references. The comparison workflow instead takes bounded, ordered chunks from two explicitly selected documents.

Do uploaded documents train the model?

The application code makes embedding and generation calls; it does not train or fine-tune a model. Selected source text is sent to the configured inference service. That implementation fact is not a blanket statement about provider retention or data use: verify the chosen service, model, and applicable terms before uploading sensitive documents.

What limits coverage and answer accuracy?

Table cells are skipped, long XML runs and paragraphs can be truncated, and chunks have no overlap. Missing embeddings, metadata filters, and bounded retrieval or comparison can leave relevant evidence out. Similarity and source citations do not prove correctness or freshness. Check extracted coverage and review every generated answer, draft, and comparison against the original documents.

Building a Document Knowledge Base with Oracle APEX and Oracle AI Vector Search was originally published in Oracle Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.