Skip to contents

Register an OpenAI-compatible endpoint

qlm_register_provider.Rd

Register a provider prefix for use in model = "provider/model" with qlm_code() and qlm_segment(). Registration lasts for this R session. Native providers in the installed ellmer always take precedence.

Usage

qlm_register_provider(provider, base_url, api_key_env, overwrite = FALSE)

Arguments

provider

A lower-case prefix containing letters, digits, underscores or hyphens, starting with a letter.

base_url

An HTTP(S) API base URL, without credentials, a query or a fragment. Include the API path, for example "https://example.org/v1".

api_key_env

Name of the environment variable holding the API key. ellmer reads its value when building the chat and making requests, and sends it as a bearer token.

overwrite

Replace an existing registration? Defaults to FALSE. Native ellmer providers cannot be replaced.

Value

The endpoint definition, invisibly.

Details

Built-in prefixes are dashscope (Alibaba Model Studio, Singapore), dashscope-cn (Beijing), moonshot (Moonshot's international endpoint), and zai (Z.AI's general API, not its Coding Plan endpoint). Both DashScope prefixes read DASHSCOPE_API_KEY; Moonshot reads MOONSHOT_API_KEY, and Z.AI reads ZHIPU_API_KEY. Keys must belong to the endpoint's region. Model names are passed through unchanged, including any slashes; the registry does not maintain a model catalogue, capability list or prices. Supply prices to qlm_code() when needed.

Use batch = FALSE with registered prefixes: ellmer currently has no batch submission method for its OpenAI-compatible provider. Registration supplies routing and credentials, not additional transport capabilities.

Explicit credentials (or ellmer's deprecated api_key) overrides the registered environment variable. Overriding base_url to a different URL requires explicit credentials, so a registered key cannot travel to another endpoint by accident. Use credentials = function() "" for an endpoint requiring no authentication.

Runs record the requested prefix and the effective openai_compatible/model, base URL and credential source. Replication and backfill reuse the recorded endpoint without consulting the registry. Supplying a replacement model resolves that model afresh. Registry entries contain environment variable names, never key values. A replication that overrides only the endpoint retains the original requested model, labelled "endpoint overridden" in print and trail output; its recorded base_url is the effective endpoint used for replay.

See also

qlm_code(), whose model argument takes a registered prefix.

Examples

qlm_register_provider("my_gateway", "https://example.org/v1", "GATEWAY_KEY")
if (FALSE) { # \dontrun{
# Another endpoint, using its own API key
qlm_register_provider(
  "minimax", "https://api.minimax.io/v1", "MINIMAX_API_KEY"
)
qlm_code(texts, codebook, model = "dashscope/qwen-plus")
qlm_code(texts, codebook, model = "my_gateway/organisation/model")
} # }