LLM Configuration and Access

An LlmNode or Agent uses a DbmsVectorChainLlmConfig component to identify the model provider, API endpoint, model, database credential, and generation settings for a model invocation.

Three separate configurations participate in an external model call:

Configuration	Responsibility
LLM configuration	Identifies the provider, endpoint, model, credential name, and request settings.
Database credential	Stores the authentication material used for the provider request.
Network access control list (ACL)	Authorizes the database principal to connect to the endpoint host.

The Agent Spec contains the credential name, but it does not contain the credential secret. The database credential and network ACL are created separately from the Agent Spec.

LLM Configuration Fields

Field	Requirement	Description
component_type	Required	Identifies the component as a DbmsVectorChainLlmConfig.
id	Required	Uniquely identifies the configuration for symbolic references.
name	Required	Provides a human-readable component name.
provider	Required	Identifies the model provider.
url	Required	Specifies the complete provider API endpoint used for model requests.
model	Required	Identifies the model requested from the provider.
credential_name	Conditionally required	Identifies the database credential used for authentication. It is required for an external provider and omitted when host is local.
host	Optional	Set to local for a supported local OpenAI-compatible or Ollama endpoint that does not use a database credential.
default_generation_parameters	Optional	Supplies supported generation settings used for model invocations.
transfer_timeout	Optional	Sets a nonnegative client-side transfer timeout, in seconds, for the provider request.

The supported generation settings are:

Field	Description
max_tokens	Limits the number of tokens generated by the model.
temperature	Controls variation in the generated response.
top_p	Controls nucleus sampling for providers that support it.
reasoning_effort	Selects a supported reasoning level for models that provide this setting.

Generation settings remain subject to the selected provider and model. A setting accepted by one provider might be unsupported or interpreted differently by another provider.

Define an LLM Configuration

The following component configures an external model:

{
  "component_type": "DbmsVectorChainLlmConfig",
  "id": "application-llm-config",
  "name": "application_llm_config",
  "provider": "example_provider",
  "url": "https://api.example.com/chat/completions",
  "model": "example_model",
  "credential_name": "AI_PROVIDER_CREDENTIAL",
  "transfer_timeout": 120,
  "default_generation_parameters": {
    "max_tokens": 512,
    "temperature": 0.2,
    "top_p": 0.9
  }
}

An LlmNode or Agent refers to this component by its id:

{
  "llm_config": {
    "$component_ref": "application-llm-config"
  }
}

The provider, url, and model values form one provider-specific configuration. The endpoint must implement the request and response format expected for the selected provider and model.

Create the Database Credential

The database credential stores the authentication material required by the model provider. The database user that creates the credential requires the applicable credential privileges and access to DBMS_VECTOR_CHAIN.CREATE_CREDENTIAL.

The following example creates an API-key credential:

BEGIN
  DBMS_VECTOR_CHAIN.CREATE_CREDENTIAL (
    CREDENTIAL_NAME => 'AI_PROVIDER_CREDENTIAL',
    PARAMS          => JSON ('{"access_token":"replace-with-provider-api-key"}')
  );
END;
/

The access_token value is an example for providers that authenticate with an API key or bearer token. Other providers can require different credential attributes. Create the credential with the payload required by the selected provider.

The name passed to CREATE_CREDENTIAL must match thecredential_name in the LLM configuration. A schema-qualified name can identify a credential in another schema when the applicable database authorization permits access to it.

Grant Network Access

An external provider request also requires a network ACL entry for the endpoint host. A database administrator grants the outbound privilege to the database principal that executes the Agent Spec.

For the endpoint
https://api.example.com/v1/chat/completions, the ACL host is api.example.com:

BEGIN
  DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE (
    HOST => 'api.example.com',
    ACE  => XS$ACE_TYPE (
              PRIVILEGE_LIST => XS$NAME_LIST ('http'),
              PRINCIPAL_NAME => 'APP_SCHEMA',
              PRINCIPAL_TYPE => XS_ACL.PTYPE_DB
            )
  );
END;
/

The ACL HOST value contains only the host name. It does not contain the https:// scheme or the endpoint path. APP_SCHEMA represents the database principal authorized to make the outbound request and must be replaced with the principal used by the application.

How the Settings Work Together

Description of the illustration LLM Provider, Credential, and Network Configuration

The credential and ACL provide different permissions. Possession of a valid credential does not grant network access, and an ACL entry does not provide provider authentication. Both must be configured for an authenticated external model request.

Configure a Local Model

A supported local OpenAI-compatible or Ollama endpoint can set host to local and omit credential_name:

{
  "component_type": "DbmsVectorChainLlmConfig",
  "id": "local-llm-config",
  "name": "local_llm_config",
  "provider": "ollama",
  "host": "local",
  "url": "http://localhost:11434/api/chat",
  "model": "<model-name>"
}

Replace with the exact model identifier recognized by the configured endpoint. For an Ollama endpoint, this is the installed model name, including its tag when applicable. The provider, url, and model values must be mutually compatible.

host and credential_name are mutually exclusive. The local setting does not make an arbitrary remote endpoint unauthenticated; it applies only to supported local provider configurations.