Add README for OCI GenAI Proxy API
Adiciona documentação inicial para a API OCI GenAI Proxy, incluindo instruções de configuração, endpoints disponíveis e exemplos de uso.
This commit is contained in:
Marcos Lohmann
487
GenAI/proxy/README.md
Normal file
487
GenAI/proxy/README.md
Normal file
@@ -0,0 +1,487 @@
|
|||||||
|
# OCI GenAI Proxy API
|
||||||
|
|
||||||
|
Proxy compatível com OpenAI v1 para modelos e agents da Oracle Cloud Infrastructure (OCI) GenAI.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Início Rápido
|
||||||
|
|
||||||
|
### **1. Configurar Modelos**
|
||||||
|
|
||||||
|
Edite `llm_models.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"gpt5": {
|
||||||
|
"id": "ocid1.generativeaimodel.oc1.us-chicago-1.amaaa...",
|
||||||
|
"region": "us-chicago-1",
|
||||||
|
"compartmentId": "ocid1.compartment.oc1..aaaaaa...",
|
||||||
|
"type": "model"
|
||||||
|
},
|
||||||
|
"my-agent": {
|
||||||
|
"id": "ocid1.generativeaiagentendpoint.oc1.us-chicago-1.amaaa...",
|
||||||
|
"region": "us-chicago-1",
|
||||||
|
"compartmentId": "ocid1.compartment.oc1..aaaaaa...",
|
||||||
|
"type": "agent"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### **2. Configurar Credenciais OCI**
|
||||||
|
|
||||||
|
Edite `credentials.conf`:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[DEFAULT]
|
||||||
|
user=ocid1.user.oc1..aaaaaa...
|
||||||
|
fingerprint=aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
|
||||||
|
tenancy=ocid1.tenancy.oc1..aaaaaa...
|
||||||
|
region=us-chicago-1
|
||||||
|
key_file=/path/to/oci_api_key.pem
|
||||||
|
```
|
||||||
|
|
||||||
|
### **3. Iniciar API**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3.11 app.py
|
||||||
|
```
|
||||||
|
|
||||||
|
API disponível em: `http://localhost:8000`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Endpoints Disponíveis
|
||||||
|
|
||||||
|
### **Compatíveis com OpenAI v1:**
|
||||||
|
- `POST /genai/{model}/v1/chat/completions` - Chat completion
|
||||||
|
- `POST /genai/{model}/v1/completions` - Text completion
|
||||||
|
- `GET /genai/{model}/v1/models` - Informações do modelo
|
||||||
|
- `POST /genai/{model}/v1/embeddings` - Embeddings (Cohere)
|
||||||
|
|
||||||
|
### **Diretos OCI:**
|
||||||
|
- `POST /genai/{model}/session` - Criar sessão (agents)
|
||||||
|
- `POST /genai/{model}/chat` - Chat com agent
|
||||||
|
- `POST /genai/{model}/inference` - Inferência direta (models)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💬 Exemplos de Uso
|
||||||
|
|
||||||
|
### **1. Chat com Model (OpenAI v1)**
|
||||||
|
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
response = requests.post(
|
||||||
|
"http://localhost:8000/genai/gpt5/v1/chat/completions",
|
||||||
|
headers={"Authorization": "Bearer YOUR_API_KEY"},
|
||||||
|
json={
|
||||||
|
"messages": [
|
||||||
|
{"role": "user", "content": "Explique computação quântica"}
|
||||||
|
],
|
||||||
|
"temperature": 0.7,
|
||||||
|
"max_tokens": 500
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
data = response.json()
|
||||||
|
print(data["choices"][0]["message"]["content"])
|
||||||
|
print(f"Tokens: {data['usage']['total_tokens']}")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **2. Chat com Agent (Modo Automático)** ⭐
|
||||||
|
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
# Primeira mensagem
|
||||||
|
response = requests.post(
|
||||||
|
"http://localhost:8000/genai/my-agent/chat",
|
||||||
|
headers={"Authorization": "Bearer YOUR_API_KEY"},
|
||||||
|
json={
|
||||||
|
"channel": "web-app",
|
||||||
|
"cuid": "user-12345",
|
||||||
|
"userMessage": "Olá, preciso de ajuda"
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
data = response.json()
|
||||||
|
print(data["agentResponse"]["content"][0]["text"])
|
||||||
|
print(f"Sessão: {data['sessionInfo']['sessionId']}")
|
||||||
|
print(f"Reutilizada: {data['sessionInfo']['reused']}")
|
||||||
|
|
||||||
|
# Segunda mensagem (mesma sessão - automático!)
|
||||||
|
response2 = requests.post(
|
||||||
|
"http://localhost:8000/genai/my-agent/chat",
|
||||||
|
headers={"Authorization": "Bearer YOUR_API_KEY"},
|
||||||
|
json={
|
||||||
|
"channel": "web-app",
|
||||||
|
"cuid": "user-12345",
|
||||||
|
"userMessage": "Qual é o status do pedido #12345?"
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
data2 = response2.json()
|
||||||
|
print(data2["agentResponse"]["content"][0]["text"])
|
||||||
|
print(f"Reutilizada: {data2['sessionInfo']['reused']}") # True
|
||||||
|
```
|
||||||
|
|
||||||
|
**Benefícios:**
|
||||||
|
- ✅ Gerenciamento automático de sessão
|
||||||
|
- ✅ Retry automático em erro 409
|
||||||
|
- ✅ Cache local com TTL de 2h
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **3. Chat com Agent (Modo Manual)**
|
||||||
|
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
# Passo 1: Criar sessão
|
||||||
|
session_resp = requests.post(
|
||||||
|
"http://localhost:8000/genai/my-agent/session",
|
||||||
|
headers={"Authorization": "Bearer YOUR_API_KEY"},
|
||||||
|
json={
|
||||||
|
"channel": "web-app",
|
||||||
|
"cuid": "user-12345"
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
session_id = session_resp.json()["id"]
|
||||||
|
|
||||||
|
# Passo 2: Enviar mensagem
|
||||||
|
chat_resp = requests.post(
|
||||||
|
"http://localhost:8000/genai/my-agent/chat",
|
||||||
|
headers={"Authorization": "Bearer YOUR_API_KEY"},
|
||||||
|
json={
|
||||||
|
"sessionId": session_id,
|
||||||
|
"userMessage": "Olá"
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
response = chat_resp.json()["agentResponse"]["content"][0]["text"]
|
||||||
|
print(response)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **4. Inferência Direta (OCI)**
|
||||||
|
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
response = requests.post(
|
||||||
|
"http://localhost:8000/genai/gpt5/inference",
|
||||||
|
headers={"Authorization": "Bearer YOUR_API_KEY"},
|
||||||
|
json={
|
||||||
|
"prompt": "Traduza para inglês: Olá, mundo!",
|
||||||
|
"temperature": 0.3,
|
||||||
|
"max_tokens": 100
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
data = response.json()
|
||||||
|
print(data["response"]["text"])
|
||||||
|
print(data["response"]["finish_reason"])
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **5. Streaming**
|
||||||
|
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
response = requests.post(
|
||||||
|
"http://localhost:8000/genai/gpt5/v1/chat/completions",
|
||||||
|
headers={"Authorization": "Bearer YOUR_API_KEY"},
|
||||||
|
json={
|
||||||
|
"messages": [{"role": "user", "content": "Conte uma história"}],
|
||||||
|
"stream": True
|
||||||
|
},
|
||||||
|
stream=True
|
||||||
|
)
|
||||||
|
|
||||||
|
for line in response.iter_lines():
|
||||||
|
if line:
|
||||||
|
print(line.decode('utf-8'))
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **6. Embeddings**
|
||||||
|
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
response = requests.post(
|
||||||
|
"http://localhost:8000/genai/gpt5/v1/embeddings",
|
||||||
|
headers={"Authorization": "Bearer YOUR_API_KEY"},
|
||||||
|
json={
|
||||||
|
"input": "Texto para gerar embedding",
|
||||||
|
"model": "cohere.embed-multilingual-v3.0"
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
data = response.json()
|
||||||
|
embedding = data["data"][0]["embedding"]
|
||||||
|
print(f"Dimensões: {len(embedding)}")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔑 Autenticação
|
||||||
|
|
||||||
|
Configure `API_KEY` no código ou use variável de ambiente:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export API_KEY="your-secret-key"
|
||||||
|
python3.11 app.py
|
||||||
|
```
|
||||||
|
|
||||||
|
Envie em todas as requisições:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Opção 1: Header Authorization
|
||||||
|
Authorization: Bearer YOUR_API_KEY
|
||||||
|
|
||||||
|
# Opção 2: Header X-API-Key
|
||||||
|
X-API-Key: YOUR_API_KEY
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Parâmetros Comuns
|
||||||
|
|
||||||
|
### **Chat Completions:**
|
||||||
|
|
||||||
|
| Parâmetro | Tipo | Descrição |
|
||||||
|
|-----------|------|-----------|
|
||||||
|
| `messages` | array | Lista de mensagens (role + content) |
|
||||||
|
| `temperature` | float | Aleatoriedade (0.0 a 2.0) |
|
||||||
|
| `max_tokens` | integer | Máximo de tokens na resposta |
|
||||||
|
| `top_p` | float | Nucleus sampling |
|
||||||
|
| `stream` | boolean | Streaming (Server-Sent Events) |
|
||||||
|
|
||||||
|
### **Chat com Agent (Modo Automático):**
|
||||||
|
|
||||||
|
| Parâmetro | Tipo | Obrigatório | Descrição |
|
||||||
|
|-----------|------|-------------|-----------|
|
||||||
|
| `channel` | string | ✅ | Canal (ex: `web-app`, `mobile-app`) |
|
||||||
|
| `cuid` | string | ✅ | Customer User ID |
|
||||||
|
| `userMessage` | string | ✅ | Mensagem do usuário |
|
||||||
|
|
||||||
|
### **Inferência Direta:**
|
||||||
|
|
||||||
|
| Parâmetro | Tipo | Descrição |
|
||||||
|
|-----------|------|-----------|
|
||||||
|
| `prompt` | string | Texto de entrada |
|
||||||
|
| `temperature` | float | Aleatoriedade (0.0 a 2.0) |
|
||||||
|
| `max_tokens` | integer | Máximo de tokens |
|
||||||
|
| `top_p` | float | Nucleus sampling |
|
||||||
|
| `top_k` | integer | Top-k sampling |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠️ Configuração Avançada
|
||||||
|
|
||||||
|
### **Modo de Teste**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export TEST_MODE=true
|
||||||
|
python3.11 app.py
|
||||||
|
```
|
||||||
|
|
||||||
|
Retorna respostas simuladas sem chamar OCI.
|
||||||
|
|
||||||
|
### **Porta Customizada**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3.11 app.py --port 9000
|
||||||
|
```
|
||||||
|
|
||||||
|
### **CORS**
|
||||||
|
|
||||||
|
CORS habilitado por padrão para `*`. Edite `app.py` para restringir.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Estrutura de Resposta
|
||||||
|
|
||||||
|
### **Chat Completion (OpenAI v1):**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "chatcmpl-abc123",
|
||||||
|
"object": "chat.completion",
|
||||||
|
"created": 1699999999,
|
||||||
|
"model": "gpt5",
|
||||||
|
"choices": [
|
||||||
|
{
|
||||||
|
"index": 0,
|
||||||
|
"message": {
|
||||||
|
"role": "assistant",
|
||||||
|
"content": "Resposta do modelo..."
|
||||||
|
},
|
||||||
|
"finish_reason": "stop"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"usage": {
|
||||||
|
"prompt_tokens": 15,
|
||||||
|
"completion_tokens": 120,
|
||||||
|
"total_tokens": 135
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### **Chat com Agent (Modo Automático):**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agentResponse": {
|
||||||
|
"role": "ASSISTANT",
|
||||||
|
"content": [
|
||||||
|
{
|
||||||
|
"text": "Resposta do agent..."
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"timeCreated": "2024-11-14T10:05:00.000Z"
|
||||||
|
},
|
||||||
|
"sessionInfo": {
|
||||||
|
"sessionId": "ocid1.generativeaiagentsession.oc1.us-chicago-1.amaaa...",
|
||||||
|
"sessionKey": "web-app:user-12345",
|
||||||
|
"reused": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### **Inferência Direta:**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"response": {
|
||||||
|
"text": "Resposta do modelo...",
|
||||||
|
"finish_reason": "STOP"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚠️ Erros Comuns
|
||||||
|
|
||||||
|
### **1. Modelo não encontrado**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"error": "Modelo 'xxx' não encontrado no arquivo de configuração"}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solução:** Adicione o modelo em `llm_models.json`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **2. Tipo incorreto**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"error": "Modelo 'gpt5' não é um agent. Use type='agent' no JSON."}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solução:** Verifique o campo `type` no `llm_models.json`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **3. Sessão expirada (modo manual)**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": "Sessão inválida ou expirada",
|
||||||
|
"suggestion": "Use modo automático com 'channel' e 'cuid'"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solução:** Use modo automático ou crie nova sessão.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **4. Autenticação inválida**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"error": "API Key inválida"}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solução:** Verifique header `Authorization` ou `X-API-Key`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Comparação: Models vs Agents
|
||||||
|
|
||||||
|
| Aspecto | Models | Agents |
|
||||||
|
|---------|--------|--------|
|
||||||
|
| **Endpoint OpenAI** | `/v1/chat/completions` | `/v1/chat/completions` |
|
||||||
|
| **Endpoint OCI** | `/inference` | `/chat` |
|
||||||
|
| **Sessão** | Não | Sim (gerenciada automaticamente) |
|
||||||
|
| **Token usage** | ✅ Sim | ❌ Não |
|
||||||
|
| **Contexto** | Stateless | Mantido na sessão |
|
||||||
|
| **Streaming** | ✅ Sim | ✅ Sim |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 Documentação Completa
|
||||||
|
|
||||||
|
Para documentação detalhada, consulte:
|
||||||
|
- `CHAT_FUSIONADO_v2.0.4.md` - Endpoint /chat com gerenciamento automático
|
||||||
|
- `ENDPOINTS_OCI_DIRETOS.md` - Endpoints diretos OCI
|
||||||
|
- `EXPLICACAO_CHAMADAS_OCI.md` - Detalhes técnicos internos
|
||||||
|
- `CHANGELOG.md` - Histórico de versões
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Resumo Rápido
|
||||||
|
|
||||||
|
### **Para Models:**
|
||||||
|
```python
|
||||||
|
# OpenAI v1 (recomendado)
|
||||||
|
POST /genai/{model}/v1/chat/completions
|
||||||
|
Body: {"messages": [...]}
|
||||||
|
|
||||||
|
# OCI direto
|
||||||
|
POST /genai/{model}/inference
|
||||||
|
Body: {"prompt": "..."}
|
||||||
|
```
|
||||||
|
|
||||||
|
### **Para Agents:**
|
||||||
|
```python
|
||||||
|
# Modo automático (recomendado)
|
||||||
|
POST /genai/{agent}/chat
|
||||||
|
Body: {"channel": "...", "cuid": "...", "userMessage": "..."}
|
||||||
|
|
||||||
|
# Modo manual
|
||||||
|
POST /genai/{agent}/session # Criar sessão
|
||||||
|
POST /genai/{agent}/chat # Enviar mensagem
|
||||||
|
Body: {"sessionId": "...", "userMessage": "..."}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📦 Versão
|
||||||
|
|
||||||
|
**v2.0.3** - Novembro 2024
|
||||||
|
|
||||||
|
**Funcionalidades:**
|
||||||
|
- ✅ Compatibilidade OpenAI v1
|
||||||
|
- ✅ Endpoints diretos OCI
|
||||||
|
- ✅ Gerenciamento automático de sessão (agents)
|
||||||
|
- ✅ Retry automático de erro 409
|
||||||
|
- ✅ Streaming
|
||||||
|
- ✅ Token usage
|
||||||
|
- ✅ Embeddings (Cohere)
|
||||||
|
- ✅ Upload de arquivos
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Suporte
|
||||||
|
|
||||||
|
Para dúvidas ou problemas, consulte a documentação completa ou abra uma issue no repositório.
|
||||||
Reference in New Issue
Block a user