AI Knowledge Configuration

Declaring a collection

A collection definition names its backend and its fields:

kind: collection
metadata:
  name: product-docs
  tenant: acme
spec:
  backend: pgvector
  fields:
    - name: title
      type: string
      searchable: true
      embedded: true
    - name: body
      type: text
      searchable: true
      embedded: true
    - name: category
      type: string
      facet: true
    - name: updated_at
      type: timestamp
      facet: true
    - name: search_blob
      type: computed
      from: [title, summary, tags]
      embedded: true
  embedding:
    model_ref: gateway:acme-embed-default
    dimensions: 1024

Note model_ref is a gateway alias, not a provider model name. Embedding calls go through the AI Gateway like every other model call, so they land in the same budgets and cost accounting, embedding a large corpus is a real expense and this is where you see it.

Choosing a backend

Backend	Choose it when
`meilisearch`	Lexical and faceted search; typo tolerance matters
`pgvector`	Semantic search alongside relational data you already have in Postgres
`milvus`	Vector volumes beyond what pgvector serves comfortably

Start on pgvector if your data already lives in Postgres, co-locating vectors with the records they describe removes a synchronisation problem that is easy to underestimate. Move to milvus when vector count, not convenience, becomes the binding constraint.

Indexing

Index one document:

POST /index/pgvector/product-docs
X-Kis-Tenant: acme
Content-Type: application/json

{
  "docid": "01JB7CY1Q6R0GK09RZAVDQGF11",
  "doctype": "product-docs",
  "contenttype": "text",
  "document": {
    "title": "Configuring intermittent reconnects",
    "body": "When a client sees ERR_CONN_4021 …",
    "category": "networking",
    "updated_at": "2026-07-01T10:00:00Z"
  }
}

Index in bulk:

POST /bulk/pgvector/product-docs
X-Kis-Tenant: acme

{ "documents": [ { "docid": "…", "document": { … } }, … ] }

docid is yours to choose and is the idempotency key, re-indexing the same docid replaces the document rather than duplicating it. Use a stable identifier from your own system, not a generated one, or every reindex doubles your corpus.

Searching

POST /search/pgvector/product-docs
X-Kis-Tenant: acme

{
  "query": "connection keeps dropping",
  "mode": "hybrid",
  "limit": 5,
  "filter": { "category": "networking" }
}

Parameter	Meaning
`query`	The search text
`mode`	`lexical`, `semantic`, `hybrid` or `entity`
`limit`	Maximum results
`filter`	Facet constraints, applied during the search
`offset`	For pagination

Deleting

DELETE /index/pgvector/product-docs/01JB7CY1Q6R0GK09RZAVDQGF11

Bulk deletion takes a list of docids, and deleting a collection removes its index entirely.

Introspection

GET /list/backends      backends available in this deployment
GET /list/documents     collections visible to the tenant

Useful in deployment checks, a collection missing from /list/documents after a deploy means its definition did not load, which is a quieter failure than an indexing error.

Operations: reindexing, throughput and monitoring