spicepod-config（香料荚配置）

Spicepod Configuration

A Spicepod manifest (spicepod.yaml) defines datasets, models, embeddings, runtime settings, and other components for a Spice application.

Spice is an open-source SQL query, search, and LLM-inference engine — not a replacement for PostgreSQL/MySQL (use those for transactional workloads) or a data warehouse (use Snowflake/Databricks for centralized analytics). Think of it as the operational data & AI layer between your applications and your data infrastructure.

Basic Structure

version: v1
kind: Spicepod
name: my_app

secrets:
  - from: env
    name: env

datasets:
  - from: <connector>:<path>
    name: <dataset_name>

models:
  - from: <provider>:<model>
    name: <model_name>

embeddings:
  - from: <provider>:<model>
    name: <embedding_name>

All Sections

Quick Start

version: v1
kind: Spicepod
name: quickstart

secrets:
  - from: env
    name: env

datasets:
  - from: postgres:public.users
    name: users
    params:
      pg_host: localhost
      pg_port: 5432
      pg_user: ${ env:PG_USER }
      pg_pass: ${ env:PG_PASS }
    acceleration:
      enabled: true
      engine: duckdb
      refresh_check_interval: 5m

models:
  - from: openai:gpt-4o
    name: assistant
    params:
      openai_api_key: ${ secrets:OPENAI_API_KEY }
      tools: auto

Runtime Configuration

Server Ports

runtime:
  http:
    enabled: true
    port: 8090
  flight:
    enabled: true
    port: 50051

Results Caching

runtime:
  caching:
    sql_results:
      enabled: true
      max_size: 128MiB
      item_ttl: 1s
      eviction_policy: lru # lru or tiny_lfu
      encoding: none # none or zstd
    search_results:
      enabled: true
      max_size: 128MiB
      item_ttl: 1s
    embeddings:
      enabled: true
      max_size: 128MiB

Stale-While-Revalidate

runtime:
  caching:
    sql_results:
      item_ttl: 10s
      stale_while_revalidate_ttl: 10s

Observability & Telemetry

runtime:
  telemetry:
    enabled: true
    otel_exporter:
      endpoint: 'localhost:4317'
      push_interval: 60s
      metrics:
        - query_duration_ms
        - query_executions

Prometheus metrics: curl http://localhost:9090/metrics

Evals

Evaluate model performance:

evals:
  - name: australia
    description: Make sure the model understands Cricket.
    dataset: cricket_logic
    scorers:
      - Match

Dependencies

Reference other Spicepods:

dependencies:
  - lukekim/demo
  - spiceai/quickstart

Full AI Application Example

version: v1
kind: Spicepod
name: ai_app

secrets:
  - from: env
    name: env

embeddings:
  - from: openai:text-embedding-3-small
    name: embed
    params:
      openai_api_key: ${ secrets:OPENAI_API_KEY }

datasets:
  - from: postgres:documents
    name: docs
    acceleration:
      enabled: true
    columns:
      - name: content
        embeddings:
          - from: embed
            row_id: id
            chunking:
              enabled: true
              target_chunk_size: 512

  - from: memory:store
    name: llm_memory
    access: read_write

models:
  - from: openai:gpt-4o
    name: assistant
    params:
      openai_api_key: ${ secrets:OPENAI_API_KEY }
      tools: auto, memory, search

CLI Commands

spice init my_app       # initialize
spice run               # start runtime
spice sql               # SQL REPL
spice chat              # chat REPL
spice status            # check status
spice datasets          # list datasets

Deployment Models

Spice ships as a single ~140MB binary with no external dependencies beyond configured data sources.

Writing Data

Spice supports writing to Apache Iceberg tables and Amazon S3 Tables via standard INSERT INTO:

datasets:
  - from: iceberg:https://catalog.example.com/v1/namespaces/sales/tables/transactions
    name: transactions
    access: read_write # required for writes

INSERT INTO transactions SELECT * FROM staging_transactions;

Use Cases

Documentation

• Spicepod Reference
• Datasets
• Runtime
• Getting Started
• Caching
• Data Acceleration
• Search
• Observability