I provider personalizzati consentono a PandaNpc di utilizzare un account API, un gateway privato o un endpoint di modello locale che controlli. Questa operazione è comunemente chiamata BYOK: porta la tua chiave. È utile quando hai bisogno di un modello al di fuori del catalogo integrato, fatturazione lato provider, un proxy interno, Ollama, LM Studio o un servizio self-hosted compatibile con OpenAI.
Per la chat diretta supportata, PandaNpc invia la richiesta al tuo endpoint configurato anziché sostituire un modello integrato. Il tuo provider a monte controlla comunque prezzi, conservazione dei dati, limiti di velocità, disponibilità dei modelli e uso accettabile.
Prerequisiti e confini di sicurezza
Prima di aggiungere un provider, raccogli:
- La chiave API del provider o il token di autenticazione locale.
- Il suo URL di base API, normalmente terminante in
/v1per un servizio compatibile con OpenAI. - L'identificatore esatto del modello accettato dall'API.
- La finestra di contesto documentata e il limite massimo di output, se prevedi di sovrascrivere le impostazioni predefinite.
Utilizza una chiave dedicata con i permessi minimi necessari e un limite di spesa dove il provider lo supporta. Non inserire mai la chiave in documentazione, prompt di chat, screenshot, output della console del browser o in un repository Git.
In un browser web, le richieste dirette sono soggette a CORS. Il provider deve consentire le richieste da https://pandanpc.com. Un URL di base come http://localhost:11434/v1 si riferisce al computer che esegue il browser, non automaticamente alla macchina PandaPaw remota. L'app desktop può essere più adatta per endpoint locali perché non è limitata dal CORS del browser allo stesso modo.
Passaggio 1: Apri la configurazione del modello
Accedi a PandaNpc e apri Model Configuration. Provider e modelli sono record separati: il provider memorizza i dettagli di connessione e autenticazione, mentre ciascun modello memorizza l'identificatore e i limiti inviati a quella connessione.
Se un provider ufficiale è già presente, configuralo o copialo invece di inventare un protocollo diverso. Per un nuovo gateway compatibile con OpenAI, seleziona Aggiungi Provider.
Passaggio 2: Aggiungi il provider
Completa il modulo del provider:
| Campo | Cosa inserire | Esempio o indicazione |
|---|---|---|
| Nome visualizzato | Un'etichetta visibile a te | Company AI Gateway |
| ID Provider | Un identificatore interno stabile | company-openai |
| API Key | Il segreto usato come token Bearer | Valore rilasciato dal provider |
| URL di base | Radice API senza /chat/completions |
https://gateway.example.com/v1 |
| Protocollo | Il formato API a monte | Scegli openai per chat completions compatibili con OpenAI |
| Segreto | Secondo segreto opzionale | Lascia vuoto a meno che il provider non lo richieda |
| Organizzazione | Identificatore organizzativo opzionale | Solo se richiesto dal provider |
| Progetto | Identificatore di progetto opzionale | Solo se richiesto dal provider |
| Supporta array di contenuto | Se il contenuto dei messaggi può utilizzare array strutturati | Mantieni abilitato per i provider che accettano contenuti di messaggi multimodali moderni |
PandaNpc rimuove gli slash finali dall'URL di base e aggiunge /chat/completions per la richiesta di chat diretta compatibile con OpenAI. Pertanto inserisci:
https://api.example.com/v1non:
https://api.example.com/v1/chat/completionsSalva il provider prima di aggiungere un modello. Quando modifichi un provider esistente, un campo API Key o Segreto vuoto significa "mantieni il valore configurato"; non espone il segreto memorizzato al modulo.
Passaggio 3: Aggiungi un modello
Scegli Aggiungi Modello sotto il provider e completa questi campi:
| Campo | Significato | Esempio |
|---|---|---|
| Nome visualizzato | Etichetta del selettore leggibile | My Coding Model |
| Valore Modello | ID esatto del modello a monte | model-name-from-provider |
| Tipo di modello | Mappatura capacità/categoria di PandaNpc | Seleziona un valore corrente dal modulo |
| Provider | Record provider creato sopra | Company AI Gateway |
| Finestra di contesto | Token totali supportati | Usa il limite intero documentato dal provider |
| Token massimi | Token di output massimi generati | Usa un valore positivo non superiore al limite del provider |
Display Name può essere modificato senza influire sulla chiamata API. Model Value non può essere dedotto da un nome di marketing; copialo dalla documentazione API del provider o dall'endpoint dell'elenco modelli.
Lascia vuoti Finestra di contesto e Token massimi quando non sei sicuro. Un valore predefinito conservativo è più sicuro che dichiarare una finestra di contesto più grande di quanto il server supporti. Questi campi sono particolarmente importanti per PandaCode perché influenzano la compattazione e la gestione del budget di output.
Esempi comuni di endpoint
I seguenti modelli illustrano la forma dell'URL; disponibilità e ID modello dipendono dalla tua installazione o dall'account del provider:
| Tipo di servizio | URL di base tipico | Note |
|---|---|---|
| API cloud compatibile con OpenAI | https://provider.example.com/v1 |
Deve supportare Chat Completions in streaming e autenticazione Bearer |
| Ollama sul computer di visualizzazione | http://localhost:11434/v1 |
Avvia l'endpoint compatibile con OpenAI di Ollama; l'uso nel browser potrebbe richiedere la configurazione CORS |
| LM Studio sul computer di visualizzazione | http://localhost:1234/v1 |
Avvia il server locale e seleziona un ID modello caricato |
| Gateway di rete privata | https://ai.internal.example/v1 |
Il client PandaNpc deve poter risolvere e raggiungere l'host |
Non dare per scontato che ogni servizio che pubblicizza "compatibile con OpenAI" implementi streaming, chiamate di strumenti, immagini, campi di ragionamento o risposte di errore identiche. Testa le funzionalità esatte di cui il tuo flusso di lavoro ha bisogno.
Verifica il provider e il modello
Usa un prompt a basso costo e non sensibile prima di fare affidamento sulla configurazione:
- Seleziona il nuovo modello in una nuova conversazione.
- Invia
Reply with exactly: provider connected. - Conferma che la risposta viene trasmessa in streaming e che la dashboard del provider registra la richiesta.
- Invia un breve messaggio di follow-up per verificare la cronologia della conversazione.
- Se hai bisogno di strumenti, immagini o contesto lungo, testa ogni funzionalità separatamente.
Per un endpoint locale, verificalo prima al di fuori di PandaNpc. Un elenco di modelli compatibile con OpenAI è spesso disponibile con:
curl http://localhost:11434/v1/modelsUsa la risposta solo per confermare la raggiungibilità e l'ID del modello. Non inserire una chiave API di produzione direttamente nella cronologia della shell.
Usa modelli personalizzati con PandaCode
PandaCode può fornire un flusso di lavoro di codifica in stile Claude Code utilizzando un backend di modello a tua scelta, inclusi DeepSeek, Qwen, un gateway compatibile con OpenAI o un servizio interno. Dopo aver configurato il provider e il modello, seleziona tale modello per la connessione o l'attività PandaCode pertinente.
Il modello deve supportare il modello di interazione richiesto dal motore di codifica. Un provider che funziona per la chat semplice potrebbe comunque fallire su chiamate di strumenti, streaming di lunga durata o contenuti strutturati. Vedi Modelli AI supportati da PandaNpc per la differenza tra modelli di chat e motori di codifica locali, e Installazione e comandi di PandaPaw per la configurazione del motore remoto.
Risoluzione dei problemi
Errore di autenticazione `401` o `403`
Crea una nuova chiave del provider, conferma che sia attiva e re-inseriscila. Verifica se il servizio a monte richiede un'organizzazione, un progetto o un metodo di autenticazione diverso. Una chiave mascherata copiata da una schermata di modifica non è il segreto originale.
Endpoint `404` o modello non trovato
Rimuovi /chat/completions dall'URL di base configurato perché PandaNpc lo aggiunge. Conferma che /v1 sia presente quando richiesto e che Valore Modello corrisponda esattamente all'ID modello a monte. Un provider può restituire lo stesso 404 sia per un URL errato che per un modello non disponibile.
Il browser segnala un errore di rete o CORS
Apri la console per sviluppatori del browser solo per identificare l'origine bloccata; non incollarvi segreti. Configura il provider per consentire https://pandanpc.com, usa il suo endpoint HTTPS o usa l'app desktop PandaNpc. Le regole sui contenuti misti impediscono a una pagina HTTPS di chiamare alcuni endpoint HTTP semplice.
Impossibile raggiungere Ollama o LM Studio locali
Assicurati che il server sia in esecuzione sullo stesso computer del client che effettua la richiesta e sia in ascolto sull'interfaccia e sulla porta configurate. Se il server del modello è in esecuzione su un altro computer, localhost è sbagliato; usa un hostname o un IP privato raggiungibile e proteggi il servizio prima di esporlo.
La risposta inizia ma si interrompe o non ha contenuto
Conferma che l'API supporti Chat Completions in streaming e emetta eventi data: standard. Riduci Token massimi, testa un messaggio di solo testo e disabilita gli array di contenuto strutturati solo se il provider documenta che accetta esclusivamente contenuto stringa.
Le sessioni lunghe falliscono vicino al limite di contesto
Riduci la Finestra di contesto configurata al limite reale supportato dal provider e riserva spazio per output, istruzioni di sistema e risultati degli strumenti. Avvia una nuova sessione dopo aver modificato la configurazione del modello in modo che i nuovi limiti vengano applicati in modo coerente.
Per i dettagli su quote e flusso di dati a livello di account, leggi Account, piani e costi API di PandaNpc e l'Informativa sulla privacy.