Skip to content

Commit 54da19a

Browse files
patelchaitanypatelchaitany
authored
feat: Making feast vector store with open ai search api compatible (#6121)
* Phase 1: Added basic open ai competible search api in the vector store Signed-off-by: Chaitany patel <patelchaitany93@gmail.com> * Added test for testing the new OpenAI api Signed-off-by: Chaitany patel <patelchaitany93@gmail.com> * fix: patch fastapi_mcp circular recursion that blocks MCP endpoint registration fastapi_mcp 0.4.0 resolve_schema_references() has no cycle detection. Feast's OpenAPI schema contains self-referential protobuf types (Value -> Struct -> Value) which trigger a RecursionError. The error is silently caught, so the /mcp route never gets registered and CI gets a 404. Add _resolve_schema_references_safe() that tracks a seen-refs set to break circular chains, and monkey-patch it into fastapi_mcp before FastApiMCP processes the schema. Non-circular schemas produce identical output to the original. Signed-off-by: Chaitany patel <patelchaitany93@gmail.com> * docs: Update filtering requirements for Postgres and SQLite backends in alpha-vector-database.md; enhance error handling in feature_server.py for invalid requests; clarify unsupported parameters in feature_store.py; ensure requested_features is a list in remote.py Signed-off-by: Chaitany patel <patelchaitany93@gmail.com> Signed-off-by: Chaitany Patel <patelchaitany93@gmail.com> * - Accept rewrite_query=false as a no-op; only reject true - Document score conversion formulas and distance metrics in alpha-vector-database.md - Add Sentence Transformers as a supported embedding provider - Fix embedding_model config example in docstring Signed-off-by: Chaitany Patel <patelchaitany93@gmail.com> * - Add GET /v1/vector_stores and GET /v1/vector_stores/{id} endpoints with RBAC enforcement (DESCRIBE permission) - Introduce VectorStoreRegistry cache that derives vs_{sha256} IDs from project + feature view name, refreshed on registry TTL cycle - Replace raw feature view names with stable vs_ identifiers in search responses (file_id, filename fields) - Update docs, blog post, and integration tests for new ID scheme - Add unit tests for VectorStoreRegistry, ID generation, and object building Signed-off-by: Chaitany Patel <patelchaitany93@gmail.com> * Remove LiteLLM embedding provider, default to Sentence Transformers Signed-off-by: Chaitany Patel <patelchaitany93@gmail.com> * Updatethe Docs, documented OpenAI search API as Alpha Signed-off-by: Chaitany Patel <patelchaitany93@gmail.com> --------- Signed-off-by: Chaitany patel <patelchaitany93@gmail.com> Signed-off-by: Chaitany Patel <patelchaitany93@gmail.com>
1 parent 294efad commit 54da19a

38 files changed

Lines changed: 3427 additions & 284 deletions

File tree

‎docs/SUMMARY.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,10 @@
205205
* [\[Beta\] On demand feature view](reference/beta-on-demand-feature-view.md)
206206
* [\[Alpha\] Static Artifacts Loading](reference/alpha-static-artifacts.md)
207207
* [\[Alpha\] Vector Database](reference/alpha-vector-database.md)
208+
* [\[Alpha\] OpenAI-Compatible Vector Store API](reference/alpha-vector-database.md#alpha-openai-compatible-vector-store-api)
209+
208210
* [Data Quality Monitoring](reference/dqm.md)
211+
* [\[Deprecated\] Data quality monitoring (Great Expectations)](reference/dqm.md)
209212
* [\[Alpha\] Streaming feature computation with Denormalized](reference/denormalized.md)
210213
* [\[Alpha\] Feature View Versioning](reference/alpha-feature-view-versioning.md)
211214
* [OpenLineage Integration](reference/openlineage.md)

‎docs/getting-started/components/feature-server.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ The Feature Server operates as a stateless service backed by two key components:
3737
| `/push` | Pushes feature data to the online and/or offline store. |
3838
| `/materialize` | Materializes features within a specific time range to the online store. |
3939
| `/materialize-incremental` | Incrementally materializes features up to the current timestamp. |
40-
| `/retrieve-online-documents` | Supports Vector Similarity Search for RAG (Alpha end-ponit) |
40+
| `/search` | Vector similarity search for RAG (Alpha endpoint) |
41+
| `/v1/vector_stores/{id}/search` | OpenAI-compatible vector search with server-side embedding |
42+
| `/retrieve-online-documents` | **Deprecated.** Use `/search` instead. |
4143
| `/docs` | API Contract for available endpoints |
4244

‎docs/getting-started/genai.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,8 @@ The MCP integration uses the `fastapi_mcp` library to automatically transform yo
226226
The fastapi_mcp integration automatically exposes your Feast feature server's FastAPI endpoints as MCP tools. This means AI assistants can:
227227

228228
* **Call `/get-online-features`** to retrieve features from the feature store
229-
* **Call `/retrieve-online-documents`** to perform vector similarity search
229+
* **Call `/search`** to perform vector similarity search (`/retrieve-online-documents` is a deprecated alias)
230+
* **Call `/v1/vector_stores/{feature_view}/search`** for OpenAI-compatible text search with server-side embedding
230231
* **Call `/write-to-online-store`** to persist agent state (memory, notes, interaction history)
231232
* **Use `/health`** to check server status
232233

‎docs/reference/alpha-vector-database.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,240 @@ backwards compatibility and the adopt industry standard naming conventions.
3333

3434
**Note**: Milvus, SQLite, and ScyllaDB implement the v2 `retrieve_online_documents_v2` method in the SDK. This will be the longer-term solution so that Data Scientists can easily enable vector similarity search by just flipping a flag.
3535

36+
## Feature server search endpoints
37+
38+
| Endpoint | Use when |
39+
|----------|----------|
40+
| `POST /search` | You have an embedding vector (or use `api_version: 2` with `query_string`) and want Feast's native online-features response format. |
41+
| `GET /v1/vector_stores` | You want to discover available vector stores and their `vs_{hash}` IDs (OpenAI-compatible). |
42+
| `GET /v1/vector_stores/{id}` | You want metadata for a specific vector store (OpenAI-compatible). |
43+
| `POST /v1/vector_stores/{id}/search` | You want plain-text queries with server-side embedding and an OpenAI-compatible response. |
44+
45+
`POST /retrieve-online-documents` is deprecated; use `POST /search` instead.
46+
47+
## [Alpha] OpenAI-Compatible Vector Store API
48+
49+
{% hint style="warning" %}
50+
**Alpha feature.** This API surface is functional and tested, but may change in future releases. Feedback and contributions are welcome.
51+
{% endhint %}
52+
53+
Feast exposes a set of [OpenAI-compatible vector store endpoints](https://platform.openai.com/docs/api-reference/vector-stores) that let clients discover, inspect, and search vector stores using plain text queries with server-side embedding. This enables integration with AI agents, LLM tool-calling frameworks, and any OpenAI-compatible client without requiring the caller to produce raw embedding vectors.
54+
55+
### Vector store IDs
56+
57+
Each feature view with at least one `vector_index=True` field is automatically assigned a deterministic identifier of the form `vs_{hash}`, where `{hash}` is the first 24 characters of `SHA-256(project + ":" + feature_view_name)`. These IDs are stable across server restarts and registry refreshes.
58+
59+
For example, a feature view named `product_catalog` in project `my_project` always maps to the same `vs_...` identifier. The listing endpoints return these IDs so clients can discover stores at runtime.
60+
61+
### Endpoints
62+
63+
| Method | Path | Permission | Description |
64+
|--------|------|------------|-------------|
65+
| `GET` | `/v1/vector_stores` | `DESCRIBE` | List all vector stores the caller has access to |
66+
| `GET` | `/v1/vector_stores/{vector_store_id}` | `DESCRIBE` | Get metadata for a single vector store |
67+
| `POST` | `/v1/vector_stores/{vector_store_id}/search` | `READ_ONLINE` | Search a vector store with a plain text query |
68+
69+
All endpoints enforce RBAC when authentication is configured. The listing endpoint filters out stores the caller cannot `DESCRIBE`.
70+
71+
### Requirements
72+
73+
1. **Embedding model** — an `embedding_model` section in `feature_store.yaml`. Feast uses [Sentence Transformers](https://www.sbert.net/) by default for local embedding — no external API key required (`pip install sentence-transformers`):
74+
75+
```yaml
76+
embedding_model:
77+
provider: sentence_transformers # default; can be omitted
78+
model: all-MiniLM-L6-v2
79+
```
80+
81+
2. **Vector-indexed feature view** — at least one feature view with `vector_index=True` on a vector field, materialized to an online store that supports vector search.
82+
83+
3. **Numeric filtering (optional)** — for metadata filters that use numeric or boolean comparisons, set `enable_openai_compatible_store: true` on your online store config and run `feast apply` to add the required `value_num` column.
84+
85+
### Custom embedding providers
86+
87+
The built-in Sentence Transformers provider works for most use cases. To use a different embedding backend (OpenAI, Cohere, a custom model, etc.), implement the `EmbeddingProvider` protocol and pass an instance to `FeatureStore`:
88+
89+
```python
90+
from feast.embedder import EmbeddingProvider
91+
92+
class MyEmbeddingProvider:
93+
def embed(self, texts: list[str]) -> list[list[float]]:
94+
# Call your embedding API here
95+
return my_model.encode(texts)
96+
97+
async def aembed(self, texts: list[str]) -> list[list[float]]:
98+
return await my_model.aencode(texts)
99+
100+
store = FeatureStore(
101+
repo_path=".",
102+
embedding_provider=MyEmbeddingProvider(),
103+
)
104+
```
105+
106+
### Numeric storage (`enable_openai_compatible_store`)
107+
108+
By default, feature values are stored as text in the online store. This means string-ordered comparisons apply (e.g., `'9' > '100'` is `true`). When `enable_openai_compatible_store: true` is set on the online store config, Feast adds a `value_num` column that stores `int`, `float`, `double`, and `bool` values natively so that numeric filters produce correct results.
109+
110+
```yaml
111+
online_store:
112+
type: postgres # or sqlite
113+
# ... connection settings ...
114+
enable_openai_compatible_store: true
115+
```
116+
117+
After changing this setting, run `feast apply` to update the database schema.
118+
119+
### List vector stores
120+
121+
```bash
122+
curl http://localhost:6566/v1/vector_stores
123+
```
124+
125+
```json
126+
{
127+
"object": "list",
128+
"data": [
129+
{
130+
"id": "vs_a1b2c3d4e5f6a1b2c3d4e5f6",
131+
"object": "vector_store",
132+
"name": "product_catalog",
133+
"status": "completed",
134+
"created_at": 1717200000
135+
}
136+
]
137+
}
138+
```
139+
140+
### Get a single vector store
141+
142+
```bash
143+
curl http://localhost:6566/v1/vector_stores/vs_a1b2c3d4e5f6a1b2c3d4e5f6
144+
```
145+
146+
Returns the same object shape as a single entry in the list response. Returns `404` if the ID does not match any vector-indexed feature view.
147+
148+
### Search
149+
150+
Start the feature server with `feast serve`, then send a search request:
151+
152+
```bash
153+
curl -X POST http://localhost:6566/v1/vector_stores/vs_a1b2c3d4e5f6a1b2c3d4e5f6/search \
154+
-H "Content-Type: application/json" \
155+
-d '{
156+
"query": "wireless noise-cancelling headphones",
157+
"max_num_results": 5
158+
}'
159+
```
160+
161+
#### Request fields
162+
163+
| Field | Type | Default | Description |
164+
|-------|------|---------|-------------|
165+
| `query` | `string` or `list[string]` | (required) | Plain text search query. Lists are joined with spaces before embedding. |
166+
| `max_num_results` | `int` | `10` | Maximum number of results to return. |
167+
| `filters` | `object` | `null` | OpenAI-style filters (see below). |
168+
| `ranking_options` | `object` | `null` | Accepted for forward compatibility, but currently ignored. Setting `score_threshold` or `ranker` inside it will return a 422 error. |
169+
| `rewrite_query` | `bool` | `null` | `false` (the default/no-op) is accepted. `true` is not yet supported and will return a 422 error. |
170+
| `metadata` | `object` | `null` | Optional. `metadata.features_to_retrieve` selects specific features. |
171+
172+
### Filters
173+
174+
The endpoint supports OpenAI-style filters for narrowing results beyond vector similarity.
175+
176+
**Comparison operators:** `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`
177+
178+
```json
179+
{"type": "eq", "key": "category", "value": "Electronics"}
180+
```
181+
182+
**Compound operators:** `and`, `or` (nest to arbitrary depth)
183+
184+
```json
185+
{
186+
"type": "and",
187+
"filters": [
188+
{"type": "eq", "key": "category", "value": "Electronics"},
189+
{"type": "gte", "key": "rating", "value": 4.5}
190+
]
191+
}
192+
```
193+
194+
For Postgres and SQLite backends, all filtering (including string equality) requires `enable_openai_compatible_store: true` in the online store config. After enabling, run `feast apply` to update the database schema.
195+
196+
ScyllaDB supports vector retrieval via `retrieve_online_documents_v2`, but OpenAI-style metadata filtering is not implemented yet. Passing `filters` raises `NotImplementedError`.
197+
198+
### Response format
199+
200+
Responses follow the OpenAI `vector_store.search_results.page` schema:
201+
202+
```json
203+
{
204+
"object": "vector_store.search_results.page",
205+
"search_query": ["wireless noise-cancelling headphones"],
206+
"data": [
207+
{
208+
"file_id": "vs_a1b2c3d4e5f6a1b2c3d4e5f6_42",
209+
"filename": "vs_a1b2c3d4e5f6a1b2c3d4e5f6",
210+
"score": 0.92,
211+
"attributes": {"name": "...", "category": "..."},
212+
"content": [
213+
{"type": "text", "text": "..."}
214+
]
215+
}
216+
],
217+
"has_more": false,
218+
"next_page": null
219+
}
220+
```
221+
222+
The `file_id` and `filename` fields use the `vs_{hash}` identifier, not raw feature view names.
223+
224+
The `score` field is a higher-is-better relevance score derived from the raw vector distance using a metric-dependent conversion:
225+
226+
| Distance metric | Conversion | Range |
227+
|----------------|------------|-------|
228+
| L2 (default) | `1 / (1 + distance)` | (0, 1] |
229+
| Cosine | `1 - distance` | [0, 1] |
230+
| Inner product / dot | `-distance` | varies |
231+
232+
The metric is determined by `vector_search_metric` on the feature view's vector field, not by an API parameter. When `features_to_retrieve` is omitted, all non-vector features are returned by default (vector embedding columns are excluded).
233+
234+
Pagination is not yet implemented; `has_more` is always `false`.
235+
236+
### SDK usage
237+
238+
The OpenAI-compatible search is also available directly via the Python SDK:
239+
240+
```python
241+
import asyncio
242+
from feast import FeatureStore
243+
244+
store = FeatureStore(repo_path=".")
245+
246+
result = asyncio.run(store.openai_search(
247+
vector_store_id="product_catalog",
248+
query="wireless noise-cancelling headphones",
249+
max_num_results=5,
250+
filters={"type": "eq", "key": "category", "value": "Electronics"},
251+
))
252+
253+
for item in result["data"]:
254+
print(f"{item['score']:.3f} {item['attributes']}")
255+
```
256+
257+
### Supported online stores
258+
259+
The OpenAI-compatible filtering has been implemented for the following online stores:
260+
261+
| Online Store | Vector Search | Metadata Filtering | Notes |
262+
|-------------|--------------|-------------------|-------|
263+
| Milvus | Yes | Yes | Boolean expressions |
264+
| Elasticsearch | Yes | Yes | Query DSL clauses |
265+
| Postgres (pgvector) | Yes | Yes | Requires `enable_openai_compatible_store: true` |
266+
| SQLite (sqlite-vec) | Yes | Yes | Requires `enable_openai_compatible_store: true` |
267+
| MongoDB | Yes | Yes | Aggregation pipeline |
268+
| ScyllaDB | Yes | No | Vector search only; metadata filters are not supported yet |
269+
36270
## Examples
37271

38272
- See the v0 [Rag Demo](https://github.com/feast-dev/feast-workshop/blob/rag/module_4_rag) for an example on how to use vector database using the `retrieve_online_documents` method (planning migration and deprecation (planning migration and deprecation).

‎docs/reference/feature-servers/python-feature-server.md‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -527,6 +527,42 @@ Prometheus adds an `instance` label per pod, so there is no
527527
duplication. Use `sum(rate(...))` or `histogram_quantile(...)` across
528528
instances as usual.
529529

530+
## Vector Search (`POST /search`)
531+
532+
The feature server exposes `POST /search` for vector similarity search against online document embeddings. Pass a pre-computed embedding in `query`, or use `api_version: 2` with `query_string` for text-based search when the online store supports it.
533+
534+
`POST /retrieve-online-documents` is a deprecated alias with the same request body and response; new integrations should use `/search`.
535+
536+
## [Alpha] OpenAI-Compatible Vector Store API
537+
538+
{% hint style="warning" %}
539+
**Alpha feature.** This API surface is functional and tested, but may change in future releases.
540+
{% endhint %}
541+
542+
The feature server exposes OpenAI-compatible vector store endpoints. This allows clients (including LLM agents and tool-calling frameworks) to discover and search vector data with plain text queries, without computing embeddings client-side.
543+
544+
Each feature view with vector-indexed fields gets a deterministic `vs_{hash}` identifier derived from `SHA-256(project + ":" + feature_view_name)`. These IDs are stable across server restarts.
545+
546+
### Endpoints
547+
548+
| Method | Path | RBAC | Description |
549+
|---|---|---|---|
550+
| `GET` | `/v1/vector_stores` | `DESCRIBE` | List all vector stores (filtered by caller permissions) |
551+
| `GET` | `/v1/vector_stores/{vector_store_id}` | `DESCRIBE` | Get metadata for a single vector store |
552+
| `POST` | `/v1/vector_stores/{vector_store_id}/search` | `READ_ONLINE` | Search a vector store with server-side embedding |
553+
554+
### Configuration
555+
556+
Add an `embedding_model` section to your `feature_store.yaml`:
557+
558+
```yaml
559+
embedding_model:
560+
provider: sentence_transformers # default; can be omitted
561+
model: all-MiniLM-L6-v2
562+
```
563+
564+
Feast uses **Sentence Transformers** (default) for local embedding inference — no external API key required. Custom embedding providers can be plugged in by implementing the `EmbeddingProvider` protocol. See [\[Alpha\] Vector Database](../alpha-vector-database.md#alpha-openai-compatible-vector-store-api) for full configuration, custom providers, filter details, and SDK usage.
565+
530566
## Starting the feature server in TLS(SSL) mode
531567

532568
Enabling TLS mode ensures that data between the Feast client and server is transmitted securely. For an ideal production environment, it is recommended to start the feature server in TLS mode.
@@ -598,7 +634,11 @@ The [PyTorch NLP template](https://github.com/feast-dev/feast/tree/main/sdk/pyth
598634
| Endpoint | Resource Type | Permission | Description |
599635
|----------------------------|---------------------------------|-------------------------------------------------------|----------------------------------------------------------------|
600636
| /get-online-features | FeatureView,OnDemandFeatureView | Read Online | Get online features from the feature store |
601-
| /retrieve-online-documents | FeatureView | Read Online | Retrieve online documents from the feature store for RAG |
637+
| /search | FeatureView | Read Online | Vector similarity search for RAG (embedding vector or text query) |
638+
| /retrieve-online-documents | FeatureView | Read Online | **Deprecated.** Use `/search` instead. |
639+
| /v1/vector_stores | FeatureView | Describe | [Alpha] List all vector stores |
640+
| /v1/vector_stores/{id} | FeatureView | Describe | [Alpha] Get a single vector store |
641+
| /v1/vector_stores/{id}/search | FeatureView | Read Online | [Alpha] OpenAI-compatible vector search with server-side embedding |
602642
| /push | FeatureView | Write Online, Write Offline, Write Online and Offline | Push features to the feature store (online, offline, or both) |
603643
| /write-to-online-store | FeatureView | Write Online | Write features to the online store |
604644
| /materialize | FeatureView | Write Online | Materialize features within a specified time range |

‎docs/reference/online-stores/scylladb.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,13 @@ result = store.retrieve_online_documents_v2(
111111
)
112112
```
113113

114+
### Metadata filtering (OpenAI-compatible)
115+
116+
ScyllaDB supports vector similarity search, but OpenAI-style metadata filtering is **not supported yet**.
117+
Passing `filters` to `retrieve_online_documents_v2` or the OpenAI-compatible search endpoint raises `NotImplementedError`.
118+
119+
For filtered vector search today, use one of the backends that implement metadata filters (for example Milvus, Elasticsearch, Postgres, SQLite, or MongoDB). See [Alpha Vector Database](../alpha-vector-database.md#supported-online-stores).
120+
114121
## Functionality Matrix
115122

116123
The set of functionality supported by online stores is described in detail [here](overview.md#functionality).

‎infra/scripts/feature_server_docker_smoke.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ def list_projects(self, allow_cache=True, tags=None):
1616
class _FakeStore:
1717
def __init__(self):
1818
self.config = SimpleNamespace()
19+
self.project = "smoke_test"
1920
self.registry = _FakeRegistry()
2021
self._provider = SimpleNamespace(
2122
async_supported=SimpleNamespace(
@@ -32,6 +33,9 @@ async def initialize(self):
3233
def refresh_registry(self):
3334
return None
3435

36+
def list_feature_views(self):
37+
return []
38+
3539
async def close(self):
3640
return None
3741

‎infra/website/docs/blog/feast-agents-mcp.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ feature_server:
5151
mcp_server_version: "1.0.0"
5252
```
5353
54-
Once enabled, any MCP-compatible agent -- whether built with LangChain, LlamaIndex, CrewAI, AutoGen, or a custom framework -- can connect to `http://your-feast-server/mcp` and discover available tools like `get-online-features` for entity-based retrieval, `retrieve-online-documents` for vector similarity search, and `write-to-online-store` for persisting agent state.
54+
Once enabled, any MCP-compatible agent -- whether built with LangChain, LlamaIndex, CrewAI, AutoGen, or a custom framework -- can connect to `http://your-feast-server/mcp` and discover available tools like `get-online-features` for entity-based retrieval, `search` for vector similarity search, `vector_store_search` for OpenAI-compatible text search, and `write-to-online-store` for persisting agent state.
5555

5656
## A Concrete Example: Customer-Support Agent with Memory
5757

@@ -338,7 +338,7 @@ export OPENAI_BASE_URL="http://localhost:11434/v1"
338338
export LLM_MODEL="llama3.1:8b"
339339
./run_demo.sh
340340
341-
# Any OpenAI-compatible provider (Azure, vLLM, LiteLLM, etc.)
341+
# Any OpenAI-compatible provider (Azure, vLLM, etc.)
342342
export OPENAI_API_KEY="your-key" # pragma: allowlist secret
343343
export OPENAI_BASE_URL="https://your-endpoint/v1"
344344
export LLM_MODEL="your-model"

0 commit comments

Comments
 (0)