OpenSearch Neural Pipelines: Embed API Docs on Write, Hybrid Rank

Keyword search alone misses “how do I rotate credentials for the orders client?” when the OpenAPI title says CredentialRotationRequest. Neural search alone misses exact error codes. Senior doc RAG on OpenSearch uses ingest pipelines to embed on write and hybrid search pipelines to fuse BM25 with k-NN at query time—so engineers get both lexical hits and semantic neighbors.

⚡ TL;DR: Register a Bedrock/SageMaker embedding model in OpenSearch; attach an ingest pipeline that fills embedding on every doc write; at query time run a search pipeline with normalization-processor + hybrid BM25/k-NN; keep API path and operationId as keyword fields for filters. See Bedrock Knowledge Bases chunking and Aurora pgvector HNSW tuning.

Ingest: embed once at write

PUT /_plugins/_ml/models/_register
{
  "name": "bedrock-titan-embed",
  "function_name": "remote",
  "connector": {
    "name": "Amazon Bedrock Connector",
    "actions": [{
      "action_type": "predict",
      "method": "POST",
      "url": "https://bedrock-runtime.${Region}.amazonaws.com/model/amazon.titan-embed-text-v2:0/invoke",
      "headers": { "content-type": "application/json", "x-amz-content-sha256": "required" },
      "request_body": "{ \"inputText\": \"${parameters.inputText}\" }"
    }]
  }
}

PUT /_ingest/pipeline/api-docs-embed
{
  "description": "Embed OpenAPI operation chunks on write",
  "processors": [
    {
      "text_embedding": {
        "model_id": "MODEL_ID",
        "field_map": { "body": "embedding" }
      }
    }
  ]
}

PUT /api-docs
{
  "settings": { "index.default_pipeline": "api-docs-embed", "index.knn": true },
  "mappings": {
    "properties": {
      "body": { "type": "text" },
      "operation_id": { "type": "keyword" },
      "path": { "type": "keyword" },
      "method": { "type": "keyword" },
      "service": { "type": "keyword" },
      "embedding": {
        "type": "knn_vector",
        "dimension": 1024,
        "method": { "name": "hnsw", "engine": "nmslib", "space_type": "cosinesimil" }
      }
    }
  }
}

Chunk by OpenAPI operation (path + method + params + responses), not by raw markdown heading alone. Do not re-embed the entire catalog on every query — that burns Bedrock spend and adds latency you already paid at ingest.

Search pipeline: hybrid rank

PUT /_search/pipeline/api-docs-hybrid
{
  "description": "Normalize + combine BM25 and neural scores",
  "phase_results_processors": [
    {
      "normalization-processor": {
        "normalization": { "technique": "min_max" },
        "combination": {
          "technique": "arithmetic_mean",
          "parameters": { "weights": [0.4, 0.6] }
        }
      }
    }
  ]
}

GET /api-docs/_search?search_pipeline=api-docs-hybrid
{
  "size": 8,
  "query": {
    "hybrid": {
      "queries": [
        {
          "multi_match": {
            "query": "rotate credentials orders client",
            "fields": ["body^2", "operation_id", "path"]
          }
        },
        {
          "neural": {
            "embedding": {
              "query_text": "rotate credentials orders client",
              "model_id": "MODEL_ID",
              "k": 12
            }
          }
        }
      ]
    }
  },
  "post_filter": { "term": { "service": "orders" } }
}

Tune BM25 vs neural weights on a golden doc-Q set. Doc answers often want slightly heavier lexical weight than pure code-symbol search.

Sync and freshness

Wire OpenAPI publish CI to bulk-index changed operations only. Store spec_hash + git_sha on each doc; delete orphans when paths disappear. Companion pattern: Bedrock Knowledge Base Sync.

# CI gate — fail if index drift > N ops vs main OpenAPI
pnpm docs:index-diff --fail-under-orphans 5

Failure modes seniors actually see

Closing checklist

Dos
– Embed on write via ingest pipeline; hybrid-rank at search
– Keep operation_id, path, service as keywords for filters
– Weight BM25 vs neural from golden evals, not vibes
– Index diffs in CI when OpenAPI changes
– Use search pipelines (normalization-processor) instead of ad-hoc client fusion

Donts
– Do not embed at query time for every keystroke
– Do not dump whole OpenAPI files as one vector
– Do not skip orphan deletes after path renames
– Do not ignore connector IAM / VPC endpoint requirements for Bedrock
– Do not ship hybrid without measuring citation precision on docs

Related reading

• Bedrock Knowledge Bases: Chunking Strategies That Fit Code RAG
• Aurora pgvector HNSW Tuning
• Code RAG Rerankers
• Cost-Aware RAG Caches

Last updated on September 11, 2026