mirror of
https://github.com/marcominerva/SqlDatabaseVectorSearch.git
synced 2026-06-20 12:23:10 +00:00
Update README.md for clarity and organization
Enhanced the README.md file with the following changes: - Added badges for .NET 9 and Blazor. - Rephrased the application overview. - Structured the Table of Contents for easier navigation. - Reformatted setup instructions for better readability. - Provided additional details for configuring the database and OpenAI settings. - Expanded the supported features section. - Included examples of API requests and responses. - Clarified limitations and FAQ sections. - Added a note about using straight SQL.
This commit is contained in:
Marco Minerva
@@ -1,9 +1,34 @@
|
||||
# SQL Database Vector Search Sample
|
||||
A repository that showcases the native VECTOR type in Azure SQL Database to perform embeddings and RAG with Azure OpenAI.
|
||||
|
||||
The application allows you to load documents, generate embeddings, save them into the database as vectors, and perform searches using Vector Search and RAG. Currently, PDF, DOCX, TXT, and MD files are supported. Vectors are saved and retrieved with Entity Framework Core using the [EFCore.SqlServer.VectorSearch](https://github.com/efcore/EfCore.SqlServer.VectorSearch) library. Embedding and Chat Completion are integrated with [Semantic Kernel](https://github.com/microsoft/semantic-kernel).
|
||||
[](https://dotnet.microsoft.com/en-us/download/dotnet/9.0) [](https://dotnet.microsoft.com/apps/aspnet/web-apps/blazor)
|
||||
|
||||
This repository contains a Blazor Web App as well as a Minimal API that allows you to programmatically interact with embeddings and RAG.
|
||||
A Blazor Web App and Minimal API for performing RAG (Retrieval Augmented Generation) and vector search using the native VECTOR type in Azure SQL Database and Azure OpenAI.
|
||||
|
||||
|
||||
## Table of Contents
|
||||
- [Overview](#overview)
|
||||
- [Screenshots](#screenshots)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Project Structure](#project-structure)
|
||||
- [Setup](#setup)
|
||||
- [Supported Features](#supported-features)
|
||||
- [How to Use](#how-to-use)
|
||||
- [Limitations & FAQ](#limitations-faq)
|
||||
- [Contributing](#contributing)
|
||||
- [License](#license)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
This application allows you to:
|
||||
- Load documents (PDF, DOCX, TXT, MD)
|
||||
- Generate embeddings and save them as vectors in Azure SQL Database
|
||||
- Perform semantic search and RAG using Azure OpenAI
|
||||
- Interact via a Blazor Web App or programmatically via Minimal API
|
||||
|
||||
Embeddings and chat completion are powered by [Semantic Kernel](https://github.com/microsoft/semantic-kernel). Vectors are managed with [EFCore.SqlServer.VectorSearch](https://github.com/efcore/EfCore.SqlServer.VectorSearch).
|
||||
|
||||
## Screenshots
|
||||
|
||||
### Web App
|
||||
|
||||
@@ -11,16 +36,41 @@ This repository contains a Blazor Web App as well as a Minimal API that allows y
|
||||
### Web API
|
||||
|
||||
|
||||
## Prerequisites
|
||||
- [.NET 9 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)
|
||||
- [Azure SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/database/single-database-create-quickstart)
|
||||
- Azure OpenAI resource and API keys
|
||||
|
||||
## Project Structure
|
||||
- `SqlDatabaseVectorSearch/` - Main Blazor Web App and API
|
||||
- `Components/` - Blazor UI components
|
||||
- `Data/` - EF Core context, migrations, and entities
|
||||
- `Endpoints/` - Minimal API endpoints
|
||||
- `Services/` - Business logic and integration services
|
||||
- `TextChunkers/` - Text splitting utilities
|
||||
- `Settings/` - Configuration classes
|
||||
|
||||
## Setup
|
||||
|
||||
- [Create an Azure SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/database/single-database-create-quickstart)
|
||||
- Open the [appsettings.json](https://github.com/marcominerva/SqlDatabaseVectorSearch/blob/master/SqlDatabaseVectorSearch/appsettings.json) file and set the connection string to the database and the other settings required by Azure OpenAI.
|
||||
- If your embedding model supports shortening, like **text-embedding-3-small** and **text-embedding-3-large**, and you want to use this feature, you need to set the [`Dimensions`](https://github.com/marcominerva/SqlDatabaseVectorSearch/blob/master/SqlDatabaseVectorSearch/appsettings.json#L17) property to the corresponding value. If your model doesn't provide this feature, or if you want to use the default size, just leave the [`Dimensions`](https://github.com/marcominerva/SqlDatabaseVectorSearch/blob/master/SqlDatabaseVectorSearch/appsettings.json#L17) property as NULL. Keep in mind that **text-embedding-3-small** has a dimension of 1536, while **text-embedding-3-large** uses vectors with 3072 elements, so with this latter model it is mandatory to specify a value (that must be less than or equal to 1998, the maximum currently supported by the VECTOR type).
|
||||
- You may need to update the size of the [`VECTOR`](https://github.com/marcominerva/SqlDatabaseVectorSearch/blob/master/SqlDatabaseVectorSearch/DataAccessLayer/ApplicationDbContext.cs?plain=1#L42C1-L42C47) column to match the size of the embedding model. The default value is 1536. Currently, the maximum allowed value is 1998. If you change it, remember to also update the [Database Migration](https://github.com/marcominerva/SqlDatabaseVectorSearch/blob/master/SqlDatabaseVectorSearch/DataAccessLayer/Migrations/00000000000000_Initial.cs?plain=1#L35C1-L35C92).
|
||||
- Run the application and start importing your documents.
|
||||
- If you want to directly use the APIs:
|
||||
- Import your documents with the `/api/documents` endpoint.
|
||||
- Ask questions using the `/api/ask` or `/api/ask-streaming` endpoints.
|
||||
1. Clone the repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/marcominerva/SqlDatabaseVectorSearch.git
|
||||
```
|
||||
|
||||
2. Configure the database and OpenAI settings
|
||||
- Edit `SqlDatabaseVectorSearch/appsettings.json` and set your Azure SQL connection string and OpenAI settings.
|
||||
- If using embedding models with shortening (e.g., `text-embedding-3-small` or `text-embedding-3-large`), set the `Dimensions` property accordingly. For `text-embedding-3-large`, you must specify a value <= 1998.
|
||||
- If you change the VECTOR size, update both the [ApplicationDbContext](SqlDatabaseVectorSearch/Data/ApplicationDbContext.cs) and the [Initial Migration](SqlDatabaseVectorSearch/Data/Migrations/00000000000000_Initial.cs).
|
||||
|
||||
3. Run the application
|
||||
|
||||
```bash
|
||||
dotnet run --project SqlDatabaseVectorSearch/SqlDatabaseVectorSearch.csproj
|
||||
```
|
||||
|
||||
5. Access the Web App
|
||||
- Navigate to `https://localhost:5001` (or the port shown in the console)
|
||||
|
||||
## Supported features
|
||||
|
||||
@@ -29,7 +79,23 @@ This repository contains a Blazor Web App as well as a Minimal API that allows y
|
||||
- **Response Streaming**: This feature enables real-time streaming of responses, allowing users to receive information as it is being processed. This ensures a seamless and efficient flow of information, enhancing the overall user experience.
|
||||
- **Citations**: The application provides citations for the sources used to justify each answer. This allows users to verify the information and understand the origin of the content provided by the system.
|
||||
|
||||
### Example of JSON response
|
||||
## How to Use
|
||||
|
||||
- **Web App**: Use the Blazor interface to upload documents, search, and chat with RAG.
|
||||
- **API**: Import documents via `POST /api/documents` and ask questions via `POST /api/ask` or `POST /api/ask-streaming`.
|
||||
|
||||
#### Example API Request
|
||||
```
|
||||
POST /api/ask
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"conversationId": "3d0bd178-499d-433a-b2bc-c35e488d9e2c"
|
||||
"text": "Why is Mars called the red planet?"
|
||||
}
|
||||
```
|
||||
|
||||
#### Example API Response
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -241,6 +307,7 @@ When using the `/api/ask-streaming` endpoint, answers will be streamed as with t
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
- The first piece of the response has the following characteristics:
|
||||
- The *streamState* property is set to `Start`.
|
||||
- It contains the question and its reformulation (if not requested, *reformulatedQuestion* will be equal to *originalQuestion*).
|
||||
@@ -248,8 +315,25 @@ When using the `/api/ask-streaming` endpoint, answers will be streamed as with t
|
||||
- Then, there are as many elements for the actual answer as necessary:
|
||||
- Each one contains a token.
|
||||
- The *streamState* property is set to `Append`.
|
||||
- *originalQuestion*, *reformulatedQuestion*, and *tokenUsage* are always `null`.
|
||||
- *originalQuestion*, *reformulatedQuestion*, *tokenUsage* and *citations* are always `null`.
|
||||
- The stream ends when an element with *streamState* equals `End` is received. This element contains token usage information for the question and the whole answer, and the list of citations.
|
||||
|
||||
## Limitations & FAQ
|
||||
|
||||
- **VECTOR column size**: Maximum allowed is 1998. For `text-embedding-3-large`, set `Dimensions` <= 1998.
|
||||
- **Supported file types**: PDF, DOCX, TXT, MD.
|
||||
- **Known Issues**: See [Issues](https://github.com/marcominerva/SqlDatabaseVectorSearch/issues)
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please open issues or pull requests. For major changes, discuss them first via an issue.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|
||||
|
||||
---
|
||||
|
||||
> [!NOTE]
|
||||
> If you prefer to use straight SQL, check out the [sql branch](https://github.com/marcominerva/SqlDatabaseVectorSearch/tree/sql).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user