> ## 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 AnythingLLM

> Platform API guide - Ace Data Cloud

[AnythingLLM](https://anythingllm.com/) è un client open source concepito per «documenti → ChatGPT privato», il cui concetto fondamentale è il **Workspace**: ogni Workspace è un insieme di documenti, un insieme di utenti e un insieme di strumenti Agent, isolati indipendentemente. È progettato specificamente per la conversazione con documenti e offre sia un'app desktop sia una versione Docker. In **LLM Provider**, include l'opzione [OpenAI (Generic)](https://docs.anythingllm.com/setup/llm-configuration/cloud/openai-generic), nella quale è possibile compilare un Base URL personalizzato, consentendo quindi di indirizzare direttamente il modello di conversazione verso Ace Data Cloud. Questo articolo presenta il processo di configurazione.

## Processo di richiesta

Per integrare Ace Data Cloud in AnythingLLM, innanzitutto vai alla [console di Ace Data Cloud](https://platform.acedata.cloud/console/applications), ottieni il tuo API Token e conservalo per l'uso successivo.

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

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

Alla prima richiesta viene offerto credito gratuito, che consente di provare gratuitamente il servizio dei modelli di Ace Data Cloud.

## Scaricare AnythingLLM

Per l'uso personale puoi scaricare la [versione desktop](https://anythingllm.com/download): il database vettoriale (LanceDB) viene eseguito localmente, la ricerca nei documenti è completamente offline e la connessione alla rete avviene solo quando viene chiamato il modello; per scenari di team con più utenti utilizza la [distribuzione Docker](https://docs.anythingllm.com/installation-docker/overview).

## Configurare il modello di conversazione

Avvia AnythingLLM, vai in **Settings → LLM Preference**, seleziona **OpenAI (Generic)** come Provider (non scegliere il normale OpenAI, che punta in modo fisso a `api.openai.com` e non dispone di un Base URL personalizzato). Consulta la documentazione ufficiale [OpenAI (Generic) LLM Provider](https://docs.anythingllm.com/setup/llm-configuration/cloud/openai-generic).

| Campo | Valore | Descrizione |
| - | - | - |
| Base URL | `https://api.acedata.cloud/v1` | **Deve terminare con `/v1`** |
| API Key | Il tuo Token Ace Data Cloud | Token copiato dalla console |
| Selected Model | ID del modello corrente | Utilizza preferibilmente l'elenco caricato automaticamente da `/models`; se non viene restituito, interrogalo con il metodo sopra descritto e compilalo manualmente |
| Model context window | Compila in base al modello selezionato | Leggi il limite massimo di contesto dal catalogo del modello corrente, non copiare i valori di altri modelli |

![Interfaccia di configurazione Generic OpenAI di AnythingLLM](https://cdn.acedata.cloud/a155f5476de7.png)

> Le capacità del modello e il limite massimo di contesto fanno riferimento al catalogo del modello corrente.

Presta attenzione alle regole del percorso del Base URL:

| 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 esiste `/v1` sotto `/openai`) |
| `https://api.acedata.cloud` | `https://api.acedata.cloud/chat/completions` | 404 (manca `/v1`) |

## Configurare il modello Embedding

Il fulcro di AnythingLLM è il RAG, che richiede un modello di embedding per vettorializzare i documenti. Le sue **Embedding Preference** e LLM Preference sono due set di configurazioni indipendenti tra loro: consulta la [panoramica della configurazione Embedder](https://docs.anythingllm.com/setup/embedder-configuration/overview). Il suo **AnythingLLM Embedder (Built-in / Native)** integrato viene eseguito direttamente in locale, funziona subito senza configurazione ed è la scelta predefinita e consigliata:

Vai in **Settings → Embedding Preference**, lascia come Provider il valore predefinito **AnythingLLM Embedder**, senza dover compilare alcuna chiave. Completerà la vettorializzazione dei documenti localmente; sia il testo originale sia i vettori vengono salvati nel LanceDB locale e non vengono caricati sul cloud.

> Le opzioni Embedder di AnythingLLM (cloud: OpenAI / Azure OpenAI / Cohere; locali: Built-in, LM Studio, [LocalAI](https://docs.anythingllm.com/setup/embedder-configuration/local/localai), Ollama) vengono tutte integrate secondo le rispettive forme fisse. Tra queste, l'embedding OpenAI cloud punta in modo fisso a `api.openai.com` e non supporta un Base URL personalizzato; se desideri utilizzare un endpoint personalizzato, puoi usare l'Embedder **Generic OpenAI** (anch'esso con un campo Base URL, che può puntare a `text-embedding-3-large` di Ace Data Cloud) oppure l'Embedder **LocalAI** locale. In questo articolo il modello di conversazione utilizza Ace Data Cloud, mentre l'embedding utilizza l'Embedder locale incluso in AnythingLLM; i due non si influenzano reciprocamente.

## Selezionare il modello

Il catalogo dei modelli viene aggiornato continuamente. Utilizza preferibilmente l'elenco dei modelli caricato automaticamente dal client; quando devi 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 chiamata di strumenti supportate dal client.

## Verificare l'integrazione

Se non sei sicuro che il problema sia in AnythingLLM o nella rete, puoi prima verificare direttamente l'endpoint con curl (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 sia il Token sia l'endpoint sono pronti; se viene restituito `HTTP 403 used_up`, significa che il Token è valido ma il saldo è insufficiente: è sufficiente ricaricare dalla [console](https://platform.acedata.cloud/console/applications).

## Avanzato: Workspace e conversazione con documenti

Dopo aver creato un nuovo Workspace, carica documenti PDF / Word / Markdown e così via. AnythingLLM li suddividerà per paragrafi, genererà vettori con l'Embedder locale e li salverà nel LanceDB locale. Durante la conversazione, recupererà prima i frammenti pertinenti, quindi passerà i frammenti e la tua domanda insieme al modello di conversazione (ovvero Ace Data Cloud) per ottenere una risposta, indicando le fonti citate sotto la risposta. Nella parte superiore di ogni Workspace puoi passare tra le modalità **Query** (risponde solo in base ai documenti) e **Chat** (mescola conoscenze generali); per scenari seri si consiglia di utilizzare la modalità Query per evitare allucinazioni. Nella distribuzione Docker puoi utilizzare variabili d'ambiente come `GENERIC_OPEN_AI_BASE_PATH`, `GENERIC_OPEN_AI_API_KEY`, `GENERIC_OPEN_AI_MODEL_PREF` per preimpostare la stessa integrazione del modello di conversazione e attivare la modalità multiutente.

## Domande frequenti

### Viene mostrato 404 / connection fail

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

### Impossibile conversare dopo aver caricato un documento

Verifica che in **Settings → Embedding Preference** sia selezionato un Embedder disponibile (il predefinito AnythingLLM Embedder può essere eseguito localmente senza configurazioni aggiuntive) e ricarica il documento per generare i vettori.

### Viene mostrato 401 Unauthorized

Assicurati che nell'API Key sia incollato il Token di Ace Data Cloud (senza prefisso `Bearer`, senza spazi aggiuntivi) e che il saldo dell'applicazione a cui appartiene sia sufficiente.

### I documenti locali verranno caricati sul cloud?

No. Il testo originale dei documenti è archiviato in LanceDB locale; solo i frammenti trovati dalla ricerca e la tua domanda verranno inviati al modello.

## Scopri di più

* [Sito ufficiale di AnythingLLM](https://anythingllm.com/) ｜ [GitHub di AnythingLLM](https://github.com/Mintplex-Labs/anything-llm) ｜ [Documentazione di distribuzione Docker](https://docs.anythingllm.com/installation-docker/overview)
* [Documentazione del provider LLM AnythingLLM OpenAI (Generic)](https://docs.anythingllm.com/setup/llm-configuration/cloud/openai-generic)
* [Panoramica della configurazione Embedder di AnythingLLM](https://docs.anythingllm.com/setup/embedder-configuration/overview)
* [Documentazione API OpenAI Chat Completions di Ace Data Cloud](https://platform.acedata.cloud/documents/openai-chat-completions)
* [Elenco dei servizi di 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.