> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Utilizzare Ace Data Cloud in Open WebUI

> Platform API guide - Ace Data Cloud

[Open WebUI](https://openwebui.com/) (in precedenza Ollama WebUI) è un client AI open source che supporta multiutente, knowledge base, RAG e deployment privato. Supporta endpoint compatibili con OpenAI personalizzati, quindi può integrarsi con Ace Data Cloud. Questo articolo presenta il processo di configurazione.

## Processo di richiesta

Per integrare Ace Data Cloud in Open WebUI, per prima cosa vai alla [console di Ace Data Cloud](https://platform.acedata.cloud/console/applications), ottieni il tuo API Token e tienilo come riserva.

![Ottenere Ace Data Cloud API Key](https://cdn.acedata.cloud/dvc3cg.jpg)

Se non hai ancora effettuato l'accesso o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso per invitarti a registrarti e accedere; dopo l'accesso e la registrazione tornerai automaticamente alla pagina corrente.

Alla prima richiesta verrà fornita una quota gratuita, con cui potrai provare gratuitamente i servizi di modelli di Ace Data Cloud.

## Distribuire e configurare Ace Data Cloud

Open WebUI si integra con endpoint compatibili con OpenAI tramite variabili d'ambiente e può essere distribuito con un comando Docker in una sola riga (sostituisci `{token}` con il tuo Token):

```bash theme={null}
docker run -d \
  --name open-webui \
  -p 3000:8080 \
  -e WEBUI_SECRET_KEY=$(openssl rand -base64 32) \
  -e OPENAI_API_BASE_URL=https://api.acedata.cloud/v1 \
  -e OPENAI_API_KEY={token} \
  -v open-webui:/app/backend/data \
  ghcr.io/open-webui/open-webui:main
```

| Variabile d'ambiente | Funzione |
| - | - |
| `OPENAI_API_BASE_URL` | Endpoint di Ace Data Cloud, **deve terminare con `/v1`** |
| `OPENAI_API_KEY` | Il tuo Token |
| `WEBUI_SECRET_KEY` | Chiave di crittografia della sessione, generata automaticamente |
| `-v open-webui:/app/backend/data` | Persistenza delle conversazioni / dati utente |

Apri `http://IP_del_tuo_server:3000`, il primo account registrato diventa automaticamente amministratore. Fai attenzione alle regole del percorso Base URL:

| OPENAI\_API\_BASE\_URL | Richiesta effettiva | Risultato |
| - | - | - |
| `https://api.acedata.cloud/v1` | `https://api.acedata.cloud/v1/chat/completions` | Corretto |
| `https://api.acedata.cloud/openai` | `https://api.acedata.cloud/openai/chat/completions` | Utilizzabile anche |
| `https://api.acedata.cloud/openai/v1` | `https://api.acedata.cloud/openai/v1/chat/completions` | 404 (non c'è `/v1` sotto `/openai`) |

Dopo l'accesso, vai in **Admin Panel → Settings → Connections** e fai clic su «Verify Connection» per verificare; in **Settings → Models** puoi filtrare e fissare i modelli utilizzati più frequentemente.

> Oltre a usare le variabili d'ambiente, Open WebUI supporta anche l'aggiunta diretta di connessioni nell'interfaccia: vai in **Admin Settings → Connections**, fai clic su ➕ e inserisci URL (`https://api.acedata.cloud/v1`) e API Key; Open WebUI chiamerà automaticamente `/models` per recuperare l'elenco dei modelli. Per i dettagli, consulta la documentazione ufficiale [Starting With OpenAI-Compatible Servers](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible).

![Interfaccia di configurazione della connessione Open WebUI Ace Data Cloud](https://cdn.acedata.cloud/f366abfd935d.png)

> `MODEL_ID` viene utilizzato solo per mostrare una allow list opzionale; se lasciato vuoto, verranno visualizzati tutti i modelli restituiti da `/models`.

## Selezionare i modelli

Il catalogo dei modelli verrà aggiornato continuamente. Dai priorità all'elenco dei modelli caricato automaticamente dal client; quando è necessario compilare manualmente, richiedi prima `GET https://api.acedata.cloud/v1/models` per ottenere l'ID del modello corrente, quindi seleziona in base alle capacità di contesto, immagini e chiamate di strumenti supportate dal client.

## Verificare l'integrazione

Se non sei sicuro che il problema sia in Open WebUI o nella rete, puoi prima usare curl per verificare direttamente l'endpoint (sostituisci `{token}` con il tuo Token):

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

La restituzione di un oggetto `chat.completion` compatibile con OpenAI indica che Token ed endpoint sono pronti; se viene restituito `HTTP 403 used_up`, significa che il Token è valido ma il saldo è insufficiente: basta ricaricare nella [console](https://platform.acedata.cloud/console/applications).

## Avanzato: knowledge base e multiutente

La knowledge base (RAG) di Open WebUI utilizza per impostazione predefinita ChromaDB per archiviare i vettori; il modello di embedding può essere impostato su `text-embedding-3-large` (tramite Ace Data Cloud), mentre gli originali dei documenti esistono solo sul tuo server e solo i frammenti trovati verranno inviati al modello. In **Admin Panel → Users** puoi gestire i ruoli utente (Pending / User / Admin); si consiglia di impostare «Default User Role» su `pending`, così i nuovi utenti potranno utilizzarlo solo dopo l'approvazione, evitando che estranei si registrino liberamente e consumino la quota. Se usi un reverse proxy nginx, aggiungi `proxy_buffering off;` e `client_max_body_size 100M;`.

## Domande frequenti

### Viene visualizzato Connection error / 404

Di solito `OPENAI_API_BASE_URL` è stato scritto come `.../openai/v1` oppure manca `/v1`. Modificalo in `https://api.acedata.cloud/v1`.

### Impossibile conversare dopo il caricamento di un documento

Nelle impostazioni RAG dell'Admin Panel, seleziona il modello di embedding `text-embedding-3-large` (provider OpenAI).

### I dati vengono persi dopo il riavvio del container

All'avvio devi montare il volume dati `-v open-webui:/app/backend/data`.

## Per saperne di più

* [Sito ufficiale di Open WebUI](https://openwebui.com/) ｜ [Open WebUI GitHub](https://github.com/open-webui/open-webui) ｜ [Documentazione di avvio rapido](https://docs.openwebui.com/getting-started/quick-start)
* [Documentazione ufficiale per l'integrazione di endpoint compatibili con OpenAI in Open WebUI](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible)
* [Documentazione API Ace Data Cloud OpenAI Chat Completions](https://platform.acedata.cloud/documents/openai-chat-completions)
* [Elenco dei servizi Ace Data Cloud](https://platform.acedata.cloud/documents)
* [Console di Ace Data Cloud](https://platform.acedata.cloud/console)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.