11 views
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 fillsembeddingon every doc write; at query time run a search pipeline withnormalization-processor+ hybrid BM25/k-NN; keep API path andoperationIdas keyword fields for filters. See Bedrock Knowledge Bases chunking and Aurora pgvector HNSW tuning.
OpenSearch Neural Pipelines: production guidance
json
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}\" }"
}]
}
}
json
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.
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" }
}
}
}
}
Search pipeline: hybrid rank
json
Tune BM25 vs neural weights on a golden doc-Q set. Doc answers often want slightly heavier lexical weight than pure code-symbol search.
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" } }
}
Sync and freshness
Wire OpenAPI publish CI to bulk-index changed operations only. Storespec_hash + git_sha on each doc; delete orphans when paths disappear. Companion pattern: Bedrock Knowledge Base Sync.
bash
# CI gate — fail if index drift > N ops vs main OpenAPI
pnpm docs:index-diff --fail-under-orphans 5
Failure modes seniors actually see
| Symptom | Cause | Fix |
|---|---|---|
| Exact error code missed | Neural-only query | Raise BM25 weight / boost body |
| Semantic miss on paraphrases | Lexical-only | Ensure neural branch + ingest embeddings |
| Stale answers after API rename | No delete-by-query on removed ops | Orphan sweep + spec_hash |
| Slow first query | Cold model / connector | Warm neural model; cache connector |
Closing checklist
Dos – Embed on write via ingest pipeline; hybrid-rank at search – Keepoperation_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
Watch: 100 Days of AI on YouTube
Short videos from CheatCoders, one AI engineering topic per day.
Most viewed
- Python Decorators Explained: From Simple Wrappers to Production Patterns
- Claude Code vs Cursor vs GitHub Copilot: Choose by Workflow, and Set Up One Repo That Works With All Three
- AI Agent Frameworks in 2025: LangGraph vs CrewAI vs AutoGen vs Raw API
- Python String Methods: Every str Method With Real Production Examples
- Css Animation Performance: Performance-Optimized Motion for Modern UIs
Newly added
- AWS Systems Manager Parameter Store: Hierarchical Runtime Config for Coding Agents
- Amazon Cognito Identity Pools: Federate Coding-Agent Tool Callers Without Long-Lived Keys
- Amazon Athena for Coding Agents: Query Tool Audit Logs and Eval Traces on S3 Without a Warehouse
- AWS Batch for Coding Agents: Parallel Overnight PR Reviews and Long-Running Jobs Without Lambda Timeouts
- Amazon Bedrock Prompt Management: Version and A/B Test Coding-Agent System Prompts
Deep-dive PDF
Get the expanded guide for this post — extra diagrams-style checklists, failure modes, and a production walkthrough. Free when you subscribe to CheatCoders.
Already subscribed? or open the subscribe page.
Discover more from CheatCoders
Subscribe to get the latest posts sent to your email.
