Creating RAG configurations

RAG configurations

A RAG configuration indexes and embeds a subset of your documents so they can be searched by vector similarity and used to answer questions.

Prerequisites

The AI Pack has to be installed first — see Installing the AI Pack for the uc_ai dependency, install_ai.sql, and the web credentials. The five AI settings are listed in the settings reference.

Embeddings can be stored in one of two vector backends, chosen per collection with the vector_store field:

• ORACLE — native Oracle AI Vector Search, available on Oracle 23ai / 26ai. Nothing external to run; no Qdrant settings needed.
• QDRANT — the external, free and open-source Qdrant vector database (hostable via its Docker image). Use this on databases without native vector support.

AI_CHUNK_FILE_LIMIT (limit of files chunked/embedded per run) applies to both. When using Qdrant, also configure:

• AI_QDRANT_COLLECTION_PREFIX: Prefix for Qdrant collection names
• AI_QDRANT_URL: URL for Qdrant service
• AI_QDRANT_WEB_CREDENTIAL_ID: APEX Web Credential Static ID for Qdrant authorization

Additionally you need an LLM provider for embedding — and optionally for answer generation, query rewriting, and LLM text extraction — configured via APEX Web Credentials.

Creating a RAG Collection

A RAG collection enables retrieval augmented generation for a subset of files in ADM. Each collection has its own configuration.

declare
  l_collection_id number;
  l_config_json clob;
begin
  l_config_json := '{"source_folder_path": ... see next chapter}';

  l_collection_id := adm_ai_rag_api.create_rag_collection(
    p_collection_name => 'test_collection',
    p_description => 'Test RAG collection',
    p_config_json => l_config_json
  );
end;

To choose which files are included, pass either a folder path or an annotation key (any file carrying that annotation, or any file in a folder carrying it). All of those files are then chunked and embedded automatically.

Configuration JSON

A collection’s configuration is a single JSON object. A few sections are required; the rest are optional add-ons you can layer on as needed:

Section / field	Required	Purpose
source_folder_path or source_file_annotation_key	Yes	Which files belong to the collection
content_type	Yes	Kind of content (currently "text")
embedding	Yes	How chunks are turned into vectors
chunks	Yes	How documents are split into chunks
distance_metric, vector_store, default_*	No	Retrieval tuning (root-level fields)
answer_model	No	LLM used by generate_answer
query_rewriting	No	Rewrite the user query before searching
llm_text_extraction	No	Extract file text with an LLM (multimodal file input) instead of the built-in filter — for messy or scanned PDFs
hybrid_search	No	Blend Oracle Text keyword search with vector search (RRF) so exact-term matches are not missed

The example below shows every section together; the reference tables that follow explain each field.

{
  "source_folder_path": "/users/philipp/rag",
  "source_file_annotation_key": "jira-articles",
  "content_type": "text",
  "distance_metric": "Cosine",
  "default_score_threshold": 0.5,
  "default_limit": 20,
  "default_max_sources": 5,
  "default_surrounding_chunks": 1,
  "embedding": {
    "dimensions": 1536,
    "provider": "openai",
    "model": "text-embedding-3-small",
    "config": {
      "g_apex_web_credential": "OPENAI_API_KEY"
    }
  },
  "chunks": {
    "target_chunk_size": 2048,
    "overlap_size": 256,
    "min_chunk_size": 512,
    "max_chunk_size": 2560
  },
  "answer_model": {
    "provider": "openai",
    "model": "gpt-4o",
    "system_prompt": "You are a support assistant. Answer using only the provided sources and cite them.",
    "config": {
      "g_apex_web_credential": "OPENAI_API_KEY",
      "g_enable_reasoning": true,
      "g_reasoning_level": "low",
      "openai": {
        "g_reasoning_effort": "low"
      }
    }
  },
  "query_rewriting": {
    "enabled": true,
    "provider": "openai",
    "model": "gpt-4o",
    "config": {
      "g_apex_web_credential": "OPENAI_API_KEY"
    }
  },
  "llm_text_extraction": {
    "provider": "google",
    "model": "gemini-2.5-flash",
    "apply_to": {
      "mime_types": ["application/pdf"]
    },
    "config": {
      "g_apex_web_credential": "GEMINI_API_KEY"
    }
  },
  "hybrid_search": {
    "enabled": true,
    "rrf_k": 60
  }
}

The generic config object

Each AI section (embedding, answer_model, query_rewriting) keeps its provider and model as explicit fields, and passes everything else through a generic config object straight to the UC AI SDK. The keys map directly onto UC AI’s settings — common keys at the root and provider-specific keys under a nested provider object:

Key	Level	Description
g_apex_web_credential	Root	APEX web credential (API key) for the provider. Replaces the old provider_web_credential.
g_base_url	Root	Base URL override for the API endpoint. Replaces the old provider_base_url_override.
g_enable_reasoning	Root	true/false — enable reasoning/thinking for models that support it.
g_reasoning_level	Root	"low", "medium" or "high". Replaces the old reasoning field.
openai.g_reasoning_effort	Provider	OpenAI reasoning effort ("minimal", "low", "medium", "high", "xhigh").
anthropic.g_max_tokens	Provider	Anthropic max output tokens.
google.g_embedding_output_dimensions	Provider	Google embedding output dimensions.

Anything UC AI supports can be set here — see the UC AI documentation for the full list of root and per-provider (openai, anthropic, google, ollama, oci, xai, openrouter) settings. The keys are validated by UC AI when a call is made, so an unknown key raises an error at generation time. config is optional and may be omitted entirely.

Configuration Fields Reference

Root Level Fields

Field	Required	Type	Description
source_folder_path	Conditional	String	The folder path within your document management system to index. Either this or source_file_annotation_key must be provided.
source_file_annotation_key	Conditional	String	An annotation key (either file or folder annotations) to filter which files should be included in the RAG collection. Either this or source_folder_path must be provided.
content_type	Yes	String	The type of content being indexed. Currently only "text" is supported.
distance_metric	No	String	The distance metric used for vector similarity search. Defaults to "Cosine". Other options may include "Euclidean" or "Dot".
vector_store	No	String	Where embeddings are stored/searched: "ORACLE" (native Oracle AI Vector Search, requires Oracle 23ai/26ai) or "QDRANT" (external Qdrant server). Materialized on create ("ORACLE" on 23ai+, otherwise "QDRANT") and cannot be changed afterwards.
default_score_threshold	No	Number	Fallback minimum similarity score (0–1) used by search/answer calls when no p_score_threshold argument is passed. If omitted it is materialized to 0.5 on create so you can tune it later. See the note below on model-dependent scales.
default_limit	No	Number	Fallback vector search top-k (how many chunks the similarity search returns) used when no p_limit argument is passed. If omitted it is materialized to 20 on create. A larger pool improves source diversity; the score threshold still filters weak matches.
default_max_sources	No	Number	Fallback maximum number of source documents returned by prepare_sources/generate_answer when no p_max_sources argument is passed. Documents are ranked by their best chunk score, so this returns the most relevant ones. If omitted it is materialized to 5 on create.
default_surrounding_chunks	No	Number	Fallback number of neighboring chunks included around each matched chunk (see the note below). 0 disables expansion. If omitted it is materialized to 1 on create.

Similarity scores are model-dependent

The score is the cosine similarity between the query and a chunk, so the useful threshold depends on your embedding model. High-similarity models like OpenAI text-embedding-3-* return relevant matches around 0.5–0.8, while others such as OCI cohere.embed-v4.0 peak much lower (relevant matches ≈ 0.3–0.45). If searches return no matches even though the collection is indexed, lower default_score_threshold for that collection.

Surrounding chunks — “embed small, retrieve big”

Small chunks embed precisely but often lack the context an LLM needs. With default_surrounding_chunks set to N, each matched chunk is returned together with its N neighboring chunks on each side. Overlapping character ranges are merged, so the source text contains each passage exactly once (this also removes the duplicated overlap text between adjacent chunks). Non-contiguous regions of a document are separated by a [...] marker.

Embedding Configuration (embedding)

These settings configure how document chunks are converted to vector embeddings.

Field	Required	Type	Description
dimensions	Yes	Number	The number of dimensions for the embedding vectors. Must match the output dimensions of your chosen embedding model (e.g., 1536 for OpenAI’s text-embedding-3-small).
provider	Yes	String	The AI provider for generating embeddings (e.g., "openai", "cohere", "ollama").
model	Yes	String	The specific embedding model to use (e.g., "text-embedding-3-small", "text-embedding-3-large").
config	No	Object	Generic UC AI config passthrough (see The generic config object). Set the API key with g_apex_web_credential and, if needed, g_base_url.

Chunking Configuration (chunks)

These settings control how documents are split into smaller chunks for processing.

Field	Required	Type	Description
target_chunk_size	Yes	Number	The target size (in characters) for each chunk. Recommended: 1024-2048.
overlap_size	Yes	Number	The number of characters that overlap between consecutive chunks. Helps preserve context. Recommended: 128-256.
min_chunk_size	Yes	Number	The minimum allowed chunk size. Chunks smaller than this may be merged with adjacent chunks.
max_chunk_size	Yes	Number	The maximum allowed chunk size. Chunks larger than this will be split further.

Answer Model Configuration (answer_model)

These settings configure the AI model used to generate answers from retrieved context. This section is optional but required if you want to use the generate_answer functionality.

Field	Required	Type	Description
provider	Yes (if section present)	String	The AI provider for generating answers (e.g., "openai", "anthropic").
model	Yes (if section present)	String	The specific model to use for answer generation (e.g., "gpt-4o", "gpt-4o-mini").
system_prompt	No	String	Custom system prompt used for answer generation when no p_system_prompt argument is passed. If omitted, a built-in prompt is used (answer only from the sources, cite them).
config	No	Object	Generic UC AI config passthrough (see The generic config object). Set the API key with g_apex_web_credential, reasoning with g_enable_reasoning + g_reasoning_level, etc.

Query Rewriting Configuration (query_rewriting)

These settings configure optional query rewriting to improve search results. The entire section is optional.

Field	Required	Type	Description
enabled	No	Boolean	Whether to enable query rewriting. Set to true to activate.
provider	Yes (if enabled)	String	The AI provider for query rewriting.
model	Yes (if enabled)	String	The model to use for rewriting queries.
config	No	Object	Generic UC AI config passthrough (see The generic config object). Set the API key with g_apex_web_credential, etc.

Text Extraction Configuration (llm_text_extraction)

By default ADM extracts a document’s text with Oracle Text’s built-in filter (the same engine used for full-text search) and stores it as the searchable content that chunks are built from. For complex or scanned PDFs this can be noisy — repeated page headers/footers, table-of-contents dot leaders, broken tables — which hurts retrieval quality.

This optional section instead sends matching files to a multimodal LLM (via file input) and stores the model’s clean transcription. It is an opt-in override: the built-in extractor still handles every file the section does not target, so adding this section never changes extraction for other file types.

Field	Required	Type	Description
provider	Yes (if section present)	String	UC AI provider whose model accepts file input (e.g. "google", "anthropic", "openai", or "oci" with a file-capable model).
model	Yes (if section present)	String	Model used to transcribe the file (e.g. "gemini-2.5-flash"). Must accept PDF/file input.
config	No	Object	Generic UC AI config passthrough (see The generic config object). Set the API key with g_apex_web_credential. For large documents raise the provider’s max output tokens (e.g. oci.g_max_tokens) so the transcription is not truncated.
prompt	No	String	Override the default extraction prompt (the default asks for a clean, complete transcription and to drop page headers/footers and TOC leaders).
apply_to	No	Object	Which files use the LLM. Defaults to { "mime_types": ["application/pdf"] }.
apply_to.mime_types	No	Array	Only these MIME types are sent to the LLM; every other type keeps the built-in extractor. Defaults to ["application/pdf"].
apply_to.annotation_key	No	String	Restrict further to documents carrying this ADM annotation — tag just the known-problem files to keep LLM cost down. Combined with mime_types (AND).
apply_to.annotation_value	No	String	Optional value the annotation must equal (requires annotation_key).

File-input support varies by provider

The model must accept documents as file input. Anthropic, Google Gemini and OpenAI support native PDF input. UC AI’s OCI provider supports PDF documents only on file-capable models such as google.gemini-2.5-flash; some OCI models (e.g. xai.grok-*) reject document input.

Queued, with retries and no silent fallback

LLM extraction runs as queued TEXT_EXTRACTION jobs with bounded retries. A failed extraction is not silently replaced by the built-in extractor; the file is retried and, after repeated failures, left unindexed. Enabling this on an existing collection only affects files extracted after the change; to re-extract already-indexed files, clear their index_content and re-run synchronisation.

Hybrid Search Configuration (hybrid_search)

By default retrieval is pure semantic vector search. Vector search can miss lexical / near-verbatim matches — exact terms, part numbers, standard codes, proper names — when their embedding similarity happens to be low. This optional section runs an Oracle Text keyword search alongside the vector search and fuses the two result lists with Reciprocal Rank Fusion (RRF), so a chunk that strongly matches the query’s words ranks highly even if its vector score is weak (and vice-versa). Absent this section, retrieval is vector-only (unchanged).

It reuses the Oracle Text index ADM already maintains on the extracted document text and maps keyword hits back to the exact chunk, so there is no extra schema and it works whether the collection’s vectors live in Oracle or Qdrant.

Field	Required	Type	Description
enabled	Yes (if section present)	Boolean	Set to true to turn hybrid retrieval on.
rrf_k	No	Number	RRF constant (default 60). Higher = flatter fusion (rank differences matter less); lower = the very top ranks dominate.
keyword_doc_candidates	No	Number	How many top keyword-matching documents to inspect for chunk-level hits (default 20).
vector_weight	No	Number	Weight of the vector result list in the fusion (default 1).
keyword_weight	No	Number	Weight of the keyword result list in the fusion (default 1). Raise above 1 to favor exact-term (lexical) matches.

Scores are RRF scores in hybrid mode

When hybrid search is enabled, the score returned by search_chunks (and avg_score from prepare_sources) is a fused RRF score, not a cosine similarity — use it for ordering, not as an absolute similarity value. score_threshold still gates the vector side only; strong keyword matches are always considered, which is how hybrid search surfaces chunks that vector search alone would drop.

Vector Index Configuration (vector_index)

Oracle vector store only — ignored when vector_store is "QDRANT".

Every key is optional. Left out entirely, a collection gets an IVF index at target accuracy 95, unpartitioned and unquantized, which is what the two materialized keys (type and target_accuracy) record on create so you can see and edit them.

The index is not fixed at creation. Edit this section with update_rag_collection, then run the reconcile:

begin
  adm_ai_vector_api.apply_index_config(p_rag_collection_id => 42);
end;
/

apply_index_config compares the configuration against what was last applied and does the least work that makes them agree — nothing, a drop-and-recreate of the index, or a rebuild of the store table when the partitioning changed. It is idempotent, so running it twice costs nothing, and it is the same call a release migration makes.

Like vector_store and the retrieval defaults, this section is carried over when an update_rag_collection config omits it. An edit to some unrelated part of the configuration will not reset the index back to the defaults and send the next reconcile off to rebuild the store.

Field	Required	Type	Description
type	No	String	"IVF" (default), "HNSW", "AUTO" or "NONE". See the note below on choosing.
target_accuracy	No	Number	Build-time target accuracy, 1–100. Defaults to 95. Oracle derives the internal parameters from it, which is why they are all optional.
parallel_degree	No	Number	Degree of parallelism for building the index, 1–1024. Omitted by default.
hnsw.neighbors	No	Number	Maximum connections per vector, 2–2048. Omit to let Oracle derive it (its own fallback is 32).
hnsw.efconstruction	No	Number	Candidates considered per insertion, 1–65535. Omit to let Oracle derive it (its own fallback is 300).
ivf.neighbor_partitions	No	Number	Target number of centroid partitions, 1–10000000. Omit to let Oracle size it from the row count.
ivf.samples_per_partition	No	Number	Vectors passed to the clustering algorithm per partition.
ivf.min_vectors_per_partition	No	Number	Trims partitions smaller than this. 0 disables trimming.
quantization.algorithm	No	String	"NONE" (default) or "SCALAR". HNSW only — rejected for IVF.
quantization.compression_ratio	No	Number	2, 4 or 8. Defaults to 4 when quantization is on.
quantization.rescore_factor	No	Number	1–100. Rescores quantized candidates against the full vectors to recover accuracy.
partitioning.enabled	No	Boolean	false by default. Hash partitions the store on the owning file and builds a LOCAL index. IVF only — Oracle does not support local HNSW indexes.
partitioning.partition_count	No	Number	Number of hash partitions, 1–1024. Defaults to 8 when partitioning is on.
search.target_accuracy	No	Number	Query-time accuracy override, 1–100. Absent means “search at the accuracy the index was built for”.
search.efsearch	No	Number	HNSW candidates to consider per query, 1–65535. Raise it above efconstruction for more accurate results.
search.neighbor_partition_probes	No	Number	IVF partitions to probe per query. Raise it for more accurate results.

"vector_index": {
  "type": "IVF",
  "target_accuracy": 95,
  "ivf": { "neighbor_partitions": 100 },
  "partitioning": { "enabled": true, "partition_count": 8 },
  "search": { "neighbor_partition_probes": 5 }
}

Choosing an index type

IVF (ORGANIZATION NEIGHBOR PARTITIONS) is the default because it needs nothing configured on the database. It works on any Oracle 23ai or 26ai instance, survives a restart, and can be partition-local.

HNSW (ORGANIZATION INMEMORY NEIGHBOR GRAPH) is faster to query, but it lives in the SGA’s vector pool and cannot be built at all unless VECTOR_MEMORY_SIZE is set. Size it at roughly 1.3 × vectors × dimensions × 4 bytes for FLOAT32 — a 100 000-chunk collection at 1536 dimensions needs about 800 MB. Ask your DBA before choosing it.

AUTO tries HNSW and falls back to IVF when the pool is unavailable. NONE builds no index: every search is an exact scan, which is 100 % accurate and adequate for a small collection.

An IVF index’s accuracy drifts as documents are added and removed. Check it with DBMS_VECTOR.INDEX_ACCURACY_QUERY and rebuild with apply_index_config(..., p_force => true) when it falls too far.

Two settings cannot be changed by reconciling

embedding.dimensions is baked into the VECTOR column and no ALTER can widen it. apply_index_config refuses a collection whose configured dimensions no longer match its store (ORA-20629) rather than discarding the embeddings — recreate the collection instead. vector_store is likewise fixed on create.

Turning partitioning on or off does rebuild the store table, and it carries every embedding across. It is not free on a large collection, but nothing is re-embedded.

Checking that the index was built

An HNSW build that fails for want of a vector pool used to be swallowed, leaving searches silently running as exact scans. It is now recorded:

select c.collection_name
     , s.index_type
     , s.index_status
     , s.partition_count
     , s.last_error
  from adm_ai_rag_vector_stores s
  join adm_ai_rag_collections c on c.rag_collection_id = s.rag_collection_id;

index_status is CREATED when the index exists, SKIPPED for type: "NONE", and FAILED with a reason in last_error when the build did not succeed.

Minimum Required Configuration

Here is the minimal configuration required to create a RAG collection:

{
  "source_folder_path": "/documents/my-folder",
  "content_type": "text",
  "embedding": {
    "dimensions": 1536,
    "provider": "openai",
    "model": "text-embedding-3-small",
    "config": {
      "g_apex_web_credential": "OPENAI_API_KEY"
    }
  },
  "chunks": {
    "target_chunk_size": 2048,
    "overlap_size": 256,
    "min_chunk_size": 512,
    "max_chunk_size": 2560
  }
}

Tips for Configuration

• Embedding Dimensions: Always verify the output dimensions of your chosen embedding model. Using incorrect dimensions will cause errors.
• Chunk Sizes: Larger chunks provide more context but may reduce precision. Smaller chunks are more precise but may lose context. Start with the recommended values and adjust based on your use case.
• Overlap: The overlap helps ensure that important information split across chunk boundaries is still captured. A value of 10-15% of the target chunk size is typical.
• Web Credentials: Create your APEX web credentials before setting up the RAG configuration. The credential names are case-sensitive.

Synchronisation

Two scheduled jobs keep a collection current, and they run at different rates because they cost very different things.

Discovery — ADM_AI_HOURLY_JOB, hourly. Works out which documents match each collection’s criteria, adds a file link for the ones that have joined, and retires the ones that have left. This is the expensive half: it re-evaluates documents against every collection’s configuration.

Processing — ADM_AI_RAG_QUEUE_JOB, every five minutes. Extracts the text of the files discovery found, chunks it, embeds the chunks, and drops the vectors of files that have left. So a document that already sits in a collection’s folder is normally searchable within minutes of being uploaded; one that has to be discovered first waits for the next hourly run.

Three settings pace the processing job. The defaults suit most installations:

Setting	Default	What it does
AI_JOB_BATCH_SIZE	10	Files or jobs per batch, and the commit unit
AI_JOB_MAX_SECONDS	240	Budget for one run; keep it below the job interval
AI_JOB_MAX_ATTEMPTS	3	Attempts before a job or a file is written off

A run that uses up its budget stops starting batches; what it did not reach stays queued for the next run five minutes later. If you want more done per run rather than more runs, raise AI_JOB_MAX_SECONDS and the job interval together — AI_JOB_MAX_SECONDS above the interval means runs overlap.

To make a collection catch up immediately rather than waiting for the next job — after changing its configuration, for instance — run the whole pipeline for it once:

begin
  adm_ai_rag_workflow_api.rag_collection_maintenance (
    p_collection_id => 1
  );
end;
/

That is what the Sync Collection button on the RAG collection page does. Discovery on its own is sync_rag_collection_files, which only decides membership and queues the work:

begin
  adm_ai_rag_workflow_api.sync_rag_collection_files (
    p_collection_id => 1
  );
end;
/

Neither call conflicts with the scheduled job: each unit of work is claimed by whichever run reaches it first, and the other skips it.

Checking on a collection

adm_ai_rag_collection_files_v gives a per-file indexing_status — PENDING, PROCESSING, INCOMPLETE, INDEXED, or ERROR with the reason in latest_error_message. A file that is failing but still inside its attempt budget shows as PENDING; it becomes ERROR once the budget is used up.

For the queue itself, adm_ai_rag_job_queue_v carries minutes_since_created, which is the lag to watch:

select job_type
     , status
     , count(*) as jobs
     , max(minutes_since_created) as oldest_minutes
  from adm_ai_rag_job_queue_v
 where status in ('PENDING', 'IN_PROGRESS')
 group by job_type, status;

What each run did is in adm_job_logs under the job id process_rag_queues, and adm_job_status records its last run and last error.

Querying RAG Collections via PL/SQL

Once your RAG collection is set up and synchronized, you can query it programmatically using the adm_ai_rag_api package.

Searching for Matching Chunks

Use search_chunks to find document chunks that match a query. This returns individual chunks with their similarity scores:

select rag_chunk_id
     , chunk_text
     , score
     , document_name
     , version_number
  from table(adm_ai_rag_api.search_chunks(
    p_rag_collection_id => 1,
    p_query             => 'How do I configure APEX authentication?',
    p_limit             => 10,
    p_score_threshold   => 0.7
  ));

Parameters:

Parameter	Type	Default	Description
p_rag_collection_id	NUMBER	Required	ID of the RAG collection to search
p_query	VARCHAR2	Required	The search query
p_limit	NUMBER	null	Maximum number of chunks to return. When null, the collection’s default_limit is used (falling back to 20).
p_score_threshold	NUMBER	null	Minimum similarity score (0-1). When null, the collection’s default_score_threshold is used (falling back to 0.5).
p_rewrite_query	BOOLEAN	null	Override: enable/disable query rewriting
p_rewrite_provider	VARCHAR2	null	Override: provider for query rewriting
p_rewrite_model	VARCHAR2	null	Override: model for query rewriting
p_rewrite_config	JSON_OBJECT_T	null	Override: generic UC AI config for query rewriting, merged over the collection’s query_rewriting.config (override keys win)

Preparing Sources

Use prepare_sources to get aggregated source documents. Matched chunks are grouped by document, documents are ranked by their best chunk score (so p_max_sources returns the most relevant ones), and each matched chunk is expanded by its surrounding chunks with overlapping ranges merged:

select document_id
     , document_name
     , version_number
     , source_text
     , chunk_count
     , avg_score
  from table(adm_ai_rag_api.prepare_sources(
    p_rag_collection_id => 1,
    p_query             => 'How do I configure APEX authentication?',
    p_limit             => 10,
    p_score_threshold   => 0.7,
    p_max_sources       => 5
  ));

Additional Parameters:

Parameter	Type	Default	Description
p_max_sources	NUMBER	null	Maximum number of source documents to return. When null, the collection’s default_max_sources is used (falling back to 5).
p_surrounding_chunks	NUMBER	null	Number of neighboring chunks included around each matched chunk (0 disables expansion). When null, the collection’s default_surrounding_chunks is used (falling back to 1).

Generating AI Answers

Use generate_answer to get an AI-generated response based on the matched sources. This requires the answer_model configuration in your collection:

declare
  l_answer clob;
begin
  l_answer := adm_ai_rag_api.generate_answer(
    p_rag_collection_id => 1,
    p_query             => 'How do I configure APEX authentication?',
    p_limit             => 10,
    p_score_threshold   => 0.5,
    p_max_sources       => 3
  );

  dbms_output.put_line(l_answer);
end;

Additional Parameters:

Parameter	Type	Default	Description
p_system_prompt	CLOB	null	Custom system prompt for answer generation. When null, the collection’s answer_model.system_prompt is used (falling back to a built-in prompt).
p_answer_provider	VARCHAR2	null	Override: provider for answer generation
p_answer_model	VARCHAR2	null	Override: model for answer generation
p_answer_config	JSON_OBJECT_T	null	Override: generic UC AI config for answer generation, merged over the collection’s answer_model.config (override keys win)
p_rewrite_config	JSON_OBJECT_T	null	Override: generic UC AI config for query rewriting, merged over the collection’s query_rewriting.config (override keys win)

Generating Answers with Debug Information

For troubleshooting and analysis, use generate_answer_debug to also capture detailed debug information:

declare
  l_answer       clob;
  l_debug_log_id number;
begin
  adm_ai_rag_api.generate_answer_debug(
    p_rag_collection_id => 1,
    p_query             => 'How do I configure APEX authentication?',
    p_limit             => 10,
    p_score_threshold   => 0.5,
    p_max_sources       => 3,
    po_answer           => l_answer,
    po_debug_log_id     => l_debug_log_id
  );

  dbms_output.put_line('Answer: ' || l_answer);
  dbms_output.put_line('Debug Log ID: ' || l_debug_log_id);
end;

The debug log contains:

• Original and rewritten queries
• All matched chunks with scores
• Prepared sources with aggregated text
• System and user prompts sent to the AI
• The AI response

Viewing Debug Logs as Markdown

Retrieve a formatted Markdown report of a debug log entry:

select adm_ai_rag_api.get_debug_log_markdown(p_debug_log_id => 123)
  from dual;

Custom System Prompts

You can customize the AI’s behavior by providing a custom system prompt:

declare
  l_answer clob;
  l_custom_prompt clob := 'You are a technical documentation expert. ' ||
    'Provide concise, code-focused answers with examples. ' ||
    'Always cite the source document name.';
begin
  l_answer := adm_ai_rag_api.generate_answer(
    p_rag_collection_id => 1,
    p_query             => 'How do I create a RESTful service?',
    p_system_prompt     => l_custom_prompt
  );

  dbms_output.put_line(l_answer);
end;

Parameter Overrides

All query functions support runtime parameter overrides for query rewriting and answer generation, so you can use different models or credentials without changing the collection configuration:

declare
  l_answer clob;
begin
  l_answer := adm_ai_rag_api.generate_answer(
    p_rag_collection_id => 1,
    p_query             => 'Explain the security model',
    p_rewrite_query     => true,
    p_rewrite_provider  => 'openai',
    p_rewrite_model     => 'gpt-4o-mini',
    p_rewrite_config    => json_object_t('{
      "g_apex_web_credential": "OPENAI_API_KEY",
      "g_base_url": "https://custom-rewrite-api.example.com/v1"
    }'),
    p_answer_provider   => 'anthropic',
    p_answer_model      => 'claude-sonnet-4-5',
    p_answer_config     => json_object_t('{
      "g_apex_web_credential": "ANTHROPIC_API_KEY",
      "g_enable_reasoning": true,
      "g_reasoning_level": "medium",
      "g_base_url": "https://custom-api.example.com/v1"
    }')
  );

  dbms_output.put_line(l_answer);
end;

Also refer to

• Installing the AI Pack
• AI agent tools — the other way to put ADM in front of an LLM: direct search and read, rather than embedded chunks
• Search and taxonomy — a collection can only embed text that was extracted; if content search finds nothing, neither will RAG
• Jobs and maintenance — ADM_AI_HOURLY_JOB is what keeps collections in sync
• Settings reference
• adm_ai_rag_api