Translate lab documentation to English
This commit is contained in:
Rodrigo Pace
@@ -1,51 +1,51 @@
|
||||
# 06 - RAG Vector Classified Docs
|
||||
|
||||
## Objetivo
|
||||
## Objective
|
||||
|
||||
Demonstrar que um agente RAG ou copilot interno so recupera documentos e chunks autorizados para o usuario final antes de enviar contexto ao LLM.
|
||||
Show that an internal RAG agent or copilot retrieves only documents and chunks authorized for the end user before sending context to the LLM.
|
||||
|
||||
## O Que Este Lab Mostra
|
||||
## What This Lab Shows
|
||||
|
||||
Antes do Oracle Deep Data Security, a busca vetorial pode recuperar chunks confidenciais de RH, juridico e executivo. Depois dos data grants, a recuperacao vetorial respeita a classificacao do documento e a persona do usuario.
|
||||
Before Oracle Deep Data Security, vector search can retrieve confidential HR, legal, and executive chunks. After data grants are applied, vector retrieval respects document classification and the user persona.
|
||||
|
||||
## Personas
|
||||
|
||||
- `nina`: colaboradora comum.
|
||||
- `heitor`: RH.
|
||||
- `sofia`: juridico.
|
||||
- `carlos`: executivo.
|
||||
- `nina`: regular employee.
|
||||
- `heitor`: HR user.
|
||||
- `sofia`: legal user.
|
||||
- `carlos`: executive user.
|
||||
|
||||
## Onde Executar Os Comandos
|
||||
## Where To Run The Commands
|
||||
|
||||
Execute os comandos a partir da raiz do repositorio:
|
||||
Run commands from the repository root:
|
||||
|
||||
```powershell
|
||||
cd C:\Users\rodrigo\Documents\Codex\oracle-deep-data-security-lab
|
||||
```
|
||||
|
||||
Conecte no banco com SQLcl ou SQL*Plus:
|
||||
Connect to the database with SQLcl or SQL*Plus:
|
||||
|
||||
```bash
|
||||
sql "<connect_string>"
|
||||
```
|
||||
|
||||
Este cenario usa tipo `VECTOR`, `TO_VECTOR` e `VECTOR_DISTANCE`. Use uma versao do banco com suporte a Oracle AI Vector Search.
|
||||
This scenario uses the `VECTOR` type, `TO_VECTOR`, and `VECTOR_DISTANCE`. Use a database version with Oracle AI Vector Search support.
|
||||
|
||||
## Passo A Passo - Antes, Ambiente Vulneravel
|
||||
## Step By Step - Before, Vulnerable Environment
|
||||
|
||||
1. Acesse o banco:
|
||||
1. Connect to the database:
|
||||
|
||||
```bash
|
||||
sql "<connect_string>"
|
||||
```
|
||||
|
||||
2. Limpe o cenario:
|
||||
2. Reset the scenario:
|
||||
|
||||
```sql
|
||||
@scenarios/06-rag-vector-classified-docs/sql/99_reset.sql
|
||||
```
|
||||
|
||||
3. Crie a tabela de chunks, embeddings simples e personas:
|
||||
3. Create the chunk table, simple embeddings, and personas:
|
||||
|
||||
```sql
|
||||
@scenarios/06-rag-vector-classified-docs/sql/00_schema.sql
|
||||
@@ -53,45 +53,45 @@ Este cenario usa tipo `VECTOR`, `TO_VECTOR` e `VECTOR_DISTANCE`. Use uma versao
|
||||
@scenarios/06-rag-vector-classified-docs/sql/02_identities.sql
|
||||
```
|
||||
|
||||
4. Simule a pergunta RAG:
|
||||
4. Simulate the RAG question:
|
||||
|
||||
```text
|
||||
Resuma documentos criticos sobre renovacoes, pessoas e riscos legais.
|
||||
Summarize critical documents about renewals, people, and legal risks.
|
||||
```
|
||||
|
||||
5. Execute a busca vetorial:
|
||||
5. Run the vector search:
|
||||
|
||||
```sql
|
||||
@scenarios/06-rag-vector-classified-docs/sql/04_test_queries.sql
|
||||
```
|
||||
|
||||
Resultado esperado antes: a busca pode recuperar chunks `HR_CONFIDENTIAL`, `LEGAL_CONFIDENTIAL` e `EXECUTIVE_CONFIDENTIAL`.
|
||||
Expected result before protection: retrieval may return `HR_CONFIDENTIAL`, `LEGAL_CONFIDENTIAL`, and `EXECUTIVE_CONFIDENTIAL` chunks.
|
||||
|
||||
## Passo A Passo - Depois, Com Deep Data Security
|
||||
## Step By Step - After, With Deep Data Security
|
||||
|
||||
1. Aplique os data grants por classificacao:
|
||||
1. Apply data grants by classification:
|
||||
|
||||
```sql
|
||||
@scenarios/06-rag-vector-classified-docs/sql/03_data_grants.sql
|
||||
```
|
||||
|
||||
2. Execute novamente a mesma busca vetorial:
|
||||
2. Run the same vector search again:
|
||||
|
||||
```sql
|
||||
@scenarios/06-rag-vector-classified-docs/sql/04_test_queries.sql
|
||||
```
|
||||
|
||||
3. Repita a demonstracao simulando `nina`, `heitor`, `sofia` e `carlos`.
|
||||
3. Repeat the demo by simulating `nina`, `heitor`, `sofia`, and `carlos`.
|
||||
|
||||
Resultado esperado depois:
|
||||
Expected result after protection:
|
||||
|
||||
- `nina` ve apenas chunks `PUBLIC` e `INTERNAL`.
|
||||
- `heitor` ve conteudo de RH autorizado.
|
||||
- `sofia` ve conteudo juridico autorizado.
|
||||
- `carlos` ve todos os documentos por perfil executivo.
|
||||
- O LLM recebe somente contexto autorizado.
|
||||
- `nina` sees only `PUBLIC` and `INTERNAL` chunks.
|
||||
- `heitor` sees authorized HR content.
|
||||
- `sofia` sees authorized legal content.
|
||||
- `carlos` sees all documents through the executive role.
|
||||
- The LLM receives only authorized context.
|
||||
|
||||
## Execucao Automatizada Opcional
|
||||
## Optional Automated Execution
|
||||
|
||||
Windows:
|
||||
|
||||
@@ -105,7 +105,7 @@ Linux/macOS:
|
||||
./scripts/run-scenario.sh 06-rag-vector-classified-docs "<connect_string>"
|
||||
```
|
||||
|
||||
## Detalhes Da Demo
|
||||
## Demo Details
|
||||
|
||||
Veja o passo a passo completo, evidencias e referencias oficiais em [RUNBOOK.md](RUNBOOK.md).
|
||||
See the complete walkthrough, evidence, and official references in [RUNBOOK.md](RUNBOOK.md).
|
||||
|
||||
|
||||
@@ -1,30 +1,30 @@
|
||||
# Runbook - 06 RAG Vector Classified Docs
|
||||
|
||||
## Objetivo
|
||||
## Objective
|
||||
|
||||
Demonstrar que um agente RAG so recupera chunks/documentos autorizados antes de enviar contexto ao LLM.
|
||||
Show that a RAG agent retrieves only authorized chunks/documents before sending context to the LLM.
|
||||
|
||||
## Valor De Seguranca
|
||||
## Security Value
|
||||
|
||||
- Reduz over-retrieval em RAG.
|
||||
- Evita que chunks confidenciais sejam enviados ao modelo.
|
||||
- Combina vector search com data grants por classificacao.
|
||||
- Reduces over-retrieval in RAG.
|
||||
- Prevents confidential chunks from being sent to the model.
|
||||
- Combines vector search with data grants by classification.
|
||||
|
||||
## Pre-Requisitos
|
||||
## Prerequisites
|
||||
|
||||
- Banco Oracle AI Database com suporte a `VECTOR`, `TO_VECTOR` e `VECTOR_DISTANCE`.
|
||||
- Banco compativel com Oracle Deep Data Security.
|
||||
- SQLcl ou SQL*Plus.
|
||||
- Oracle AI Database with support for `VECTOR`, `TO_VECTOR`, and `VECTOR_DISTANCE`.
|
||||
- Database compatible with Oracle Deep Data Security.
|
||||
- SQLcl or SQL*Plus.
|
||||
|
||||
## Antes - Ambiente Vulneravel
|
||||
## Before - Vulnerable Environment
|
||||
|
||||
1. Limpe o cenario:
|
||||
1. Reset the scenario:
|
||||
|
||||
```sql
|
||||
@scenarios/06-rag-vector-classified-docs/sql/99_reset.sql
|
||||
```
|
||||
|
||||
2. Crie chunks e personas, sem aplicar data grants:
|
||||
2. Create chunks and personas without applying data grants:
|
||||
|
||||
```sql
|
||||
@scenarios/06-rag-vector-classified-docs/sql/00_schema.sql
|
||||
@@ -32,52 +32,52 @@ Demonstrar que um agente RAG so recupera chunks/documentos autorizados antes de
|
||||
@scenarios/06-rag-vector-classified-docs/sql/02_identities.sql
|
||||
```
|
||||
|
||||
3. Simule a pergunta RAG:
|
||||
3. Simulate the RAG question:
|
||||
|
||||
```text
|
||||
Resuma documentos criticos sobre renovacoes, pessoas e riscos legais.
|
||||
Summarize critical documents about renewals, people, and legal risks.
|
||||
```
|
||||
|
||||
4. Execute a busca vetorial:
|
||||
4. Run the vector search:
|
||||
|
||||
```sql
|
||||
@scenarios/06-rag-vector-classified-docs/sql/04_test_queries.sql
|
||||
```
|
||||
|
||||
## Resultado Esperado Antes
|
||||
## Expected Result Before
|
||||
|
||||
- A busca pode recuperar chunks `HR_CONFIDENTIAL`, `LEGAL_CONFIDENTIAL` e `EXECUTIVE_CONFIDENTIAL`.
|
||||
- O LLM poderia receber contexto sensivel antes mesmo de gerar a resposta.
|
||||
- The search may retrieve `HR_CONFIDENTIAL`, `LEGAL_CONFIDENTIAL`, and `EXECUTIVE_CONFIDENTIAL` chunks.
|
||||
- The LLM could receive sensitive context before it even generates an answer.
|
||||
|
||||
## Depois - Aplicando Deep Data Security
|
||||
## After - Applying Deep Data Security
|
||||
|
||||
1. Aplique data grants por classificacao:
|
||||
1. Apply data grants by classification:
|
||||
|
||||
```sql
|
||||
@scenarios/06-rag-vector-classified-docs/sql/03_data_grants.sql
|
||||
```
|
||||
|
||||
2. Execute a mesma busca como `nina`, `heitor`, `sofia` e `carlos`:
|
||||
2. Run the same search as `nina`, `heitor`, `sofia`, and `carlos`:
|
||||
|
||||
```sql
|
||||
@scenarios/06-rag-vector-classified-docs/sql/04_test_queries.sql
|
||||
```
|
||||
|
||||
## Resultado Esperado Depois
|
||||
## Expected Result After
|
||||
|
||||
- `nina` recupera apenas `PUBLIC` e `INTERNAL`.
|
||||
- `heitor` recupera conteudo de RH autorizado.
|
||||
- `sofia` recupera conteudo juridico autorizado.
|
||||
- `carlos` recupera todos os chunks por papel executivo.
|
||||
- A camada RAG so envia contexto autorizado ao LLM.
|
||||
- `nina` retrieves only `PUBLIC` and `INTERNAL` chunks.
|
||||
- `heitor` retrieves authorized HR content.
|
||||
- `sofia` retrieves authorized legal content.
|
||||
- `carlos` retrieves all chunks through the executive role.
|
||||
- The RAG layer sends only authorized context to the LLM.
|
||||
|
||||
## Evidencias Para Demo
|
||||
## Demo Evidence
|
||||
|
||||
- Lista de chunks recuperados antes/depois.
|
||||
- Classificacoes visiveis por persona.
|
||||
- Explicacao de que o controle ocorre antes da chamada ao LLM.
|
||||
- Retrieved chunk list before and after protection.
|
||||
- Visible classifications by persona.
|
||||
- Explanation that enforcement happens before the LLM call.
|
||||
|
||||
## Referencias Oficiais
|
||||
## Official References
|
||||
|
||||
- Oracle Deep Data Security Guide: https://docs.oracle.com/en/database/oracle/oracle-database/26/ddscg/index.html
|
||||
- Create Data Grants: https://docs.oracle.com/en/database/oracle/oracle-database/26/ddscg/create-data-grants.html
|
||||
|
||||
Reference in New Issue
Block a user