Skip to contents

Parallel LLM Processing with Tibble-Based Experiments (Core Engine)

Source: R/LLM_parallel_utils.R
call_llm_par.Rd

Processes experiments from a tibble where each row contains a config and message pair. This is the core parallel processing function. Metadata columns are preserved. Use setup_llm_parallel() when you want explicit control over workers.

Usage

call_llm_par(
  experiments,
  simplify = TRUE,
  tries = 10,
  wait_seconds = 2,
  backoff_factor = 120^(1/tries),
  verbose = FALSE,
  memoize = FALSE,
  max_workers = NULL,
  progress = FALSE,
  json_output = NULL,
  start_jitter = 0,
  .request_hash = FALSE
)

Arguments

experiments

A tibble/data.frame with required list-columns 'config' (llm_config objects) and 'messages' (character vector OR message list).

simplify

If TRUE (default), provider, model, and the model parameters stored in each row's config are unnested into regular columns for easy filtering and grouping.

tries

Integer. Total number of attempts per call (first call plus retries). Default is 10.

wait_seconds

Numeric. Initial wait time (seconds) before retry. Default is 2.

backoff_factor

Numeric. Multiplier for wait time after each failure. Default is 3.

verbose

Logical. If TRUE, prints progress and debug information.

memoize

Logical. If TRUE, enables caching for identical requests. Note that under a multisession plan each worker process keeps its own cache, so deduplication is per worker, not global.

max_workers

Integer. Maximum number of parallel workers. If NULL, auto-detects.

progress

Logical. If TRUE, shows progress bar.

json_output

Deprecated. Raw JSON string is always included as raw_response_json. This parameter is kept for backward compatibility but has no effect.

start_jitter

Each call starts after a uniformly distributed delay between 0 and start_jitter seconds. The default is 0 (no delay); set a few seconds when launching very large runs against a provider with strict burst limits.

.request_hash

Logical. If TRUE, append a request_hash column (the same key llm_request_hash() produces) so the results can be joined to the audit log. Default FALSE; the column is omitted unless requested. See also llm_add_request_hash().

Value

A tibble containing all original columns plus:

  • response_text - assistant text (or NA on failure)

  • raw_response_json - raw JSON string (on failure: the provider's error body when available)

  • success, error_message

  • finish_reason - e.g. "stop", "length", "filter", "tool", or "error:category"

  • sent_tokens, rec_tokens, total_tokens, reasoning_tokens

  • response_id

  • duration - seconds

  • status_code, error_code, bad_param - error diagnostics (NA on success)

  • response - the full llmr_response object (or NULL on failure)

The response column holds llmr_response objects on success, or NULL on failure.

Parallel Workflow

Recommended workflow:

  1. Call setup_llm_parallel() once at the start of your script.

  2. Run one or more parallel experiments (e.g., call_llm_broadcast()).

  3. Call reset_llm_parallel() at the end to restore sequential processing. If the active future plan is sequential, this function temporarily switches to multisession for the duration of the call.

See also

For setting up the environment: setup_llm_parallel, reset_llm_parallel. For simpler, pre-configured parallel tasks: call_llm_broadcast, call_llm_sweep, call_llm_compare. For creating experiment designs: build_factorial_experiments.

Examples

if (FALSE) { # \dontrun{
# Simple example: Compare two models on one prompt
cfg1 <- llm_config("openai", "gpt-4.1-nano")
cfg2 <- llm_config("groq", "openai/gpt-oss-20b")

experiments <- tibble::tibble(
  model_id = c("gpt-4.1-nano", "groq-gpt-oss-20b"),
  config = list(cfg1, cfg2),
  messages = "Count the number of the letter e in this word: Freundschaftsbeziehungen "
)

setup_llm_parallel(workers = 2)
results <- call_llm_par(experiments, progress = TRUE)
reset_llm_parallel()

print(results[, c("model_id", "response_text")])

} # }