> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel-docs-benchmark-writeup-and-tooling.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Oracle GenAI

> Configure Oracle GenAI's OpenAI-compatible endpoint in GoModel, including the required OCI policy and configured model lists.

GoModel calls Oracle Generative AI through Oracle's OpenAI-compatible inference
endpoint. Setup needs an OCI IAM policy for `generativeaiapikey`, a
region-specific base URL, and a configured model list (Oracle's `/models` is
not reliably available on the API-key flow).

## 1. Add the OCI policy

```text theme={null}
Allow any-user to use generative-ai-family in tenancy where ALL {request.principal.type='generativeaiapikey'}
```

This tenancy-level policy is enough for testing. In production, narrow it to a
compartment, API key, or specific model.

## 2. Configure

```bash theme={null}
ORACLE_BASE_URL=https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1
ORACLE_API_KEY=...
ORACLE_MODELS=openai.gpt-oss-120b,xai.grok-3
GOMODEL_MASTER_KEY=change-me
```

`ORACLE_MODELS` is a comma-separated list (whitespace trimmed). Behavior
follows the global `CONFIGURED_PROVIDER_MODELS_MODE` — `fallback` (default)
uses the list when Oracle's `/models` is unavailable or empty; `allowlist`
exposes only configured models and skips the upstream call.

Or in `config.yaml`:

```yaml theme={null}
providers:
  oracle:
    type: oracle
    base_url: "${ORACLE_BASE_URL}"
    api_key: "${ORACLE_API_KEY}"
    models:
      - openai.gpt-oss-120b
```

If both are set, `ORACLE_MODELS` overrides YAML `models:` for the matching
provider.

## 3. Run GoModel

<CodeGroup>
  ```bash Docker (.env file) theme={null}
  docker run --rm -p 8080:8080 --env-file .env enterpilot/gomodel
  ```

  ```bash Docker (inline -e) theme={null}
  docker run --rm -p 8080:8080 \
    -e GOMODEL_MASTER_KEY="change-me" \
    -e ORACLE_BASE_URL="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1" \
    -e ORACLE_API_KEY="..." \
    -e ORACLE_MODELS="openai.gpt-oss-120b,xai.grok-3" \
    enterpilot/gomodel
  ```

  ```bash Binary (make build) theme={null}
  make build
  ./bin/gomodel
  ```
</CodeGroup>

## 4. Verify

```bash theme={null}
curl -s http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai.gpt-oss-120b",
    "messages": [{"role": "user", "content": "Reply with the single word ok."}],
    "max_tokens": 80
  }'
```

`GET /v1/models` returns models such as `openai.gpt-oss-120b` with
`owned_by: "oracle"`. Responses API works the same way.

<Note>
  Use a high enough `max_tokens` budget. Some Oracle-backed reasoning models
  can spend short completions on reasoning content before emitting final
  assistant text.
</Note>

## Multiple Oracle providers

Use suffixed env vars to register a second Oracle instance:

```bash theme={null}
ORACLE_US_BASE_URL=https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1
ORACLE_US_API_KEY=...
ORACLE_US_MODELS=openai.gpt-oss-120b
```

This registers provider `oracle-us`. Reach for YAML only when generated names
don't fit or you want per-provider resilience overrides.

## Not yet integrated

* Native OCI-based model auto-discovery (would remove the need for
  `ORACLE_MODELS` / YAML `models:`).
* Reliable use of Oracle's OpenAI-compatible `/models` endpoint on the API-key
  flow.

## Troubleshooting

* **`404 Authorization failed or requested resource not found`** — missing OCI
  policy, wrong region, or model not available to the account.
* **`model registry has no models`** — set `ORACLE_MODELS` or YAML `models:`.
* **OCI CLI works but Oracle bearer requests fail** — different auth flows.
  OCI CLI uses API signing keys; Oracle Generative AI inference uses the
  Generative AI bearer API key.

## References

* [Oracle API keys overview](https://docs.oracle.com/en-us/iaas/Content/generative-ai/api-keys.htm)
* [Oracle API key permissions](https://docs.oracle.com/en-us/iaas/Content/generative-ai/add-api-permission.htm)
* [Oracle OpenAI-compatible endpoint](https://docs.oracle.com/en-us/iaas/Content/generative-ai/oci-openai.htm)