mirror of
https://github.com/crowetic/nc-talk-ai.git
synced 2026-09-07 07:32:31 +00:00
Pascal Kienast
43ba436a61
- Rewrite the four longest guides (RAG background jobs, webhook debug, bot setup, onboarding) at roughly half the length: drop historical bug-fix notes, duplicated command blocks, ASCII mega-diagrams and filler sections, keep everything operationally useful. - Remove provider-specific recommendations; examples are now neutral OpenAI-compatible endpoints. - Fix stale content: dead doc links in docs/README.md, old repo issue URLs, catalogue tools (now provided via the tool-provider extension point, not built-in), supported NC versions, clone URL in quick start. - Slim DEVELOPMENT.md down to build/test/migration essentials. docs/ shrinks from 2850 to 1278 lines with no loss of setup, debugging or architecture coverage.
114 lines
2.9 KiB
Markdown
114 lines
2.9 KiB
Markdown
# Talk AI Quick Start
|
|
|
|
This guide gets a working Talk AI installation from source into Nextcloud.
|
|
|
|
## 1. Install And Build
|
|
|
|
Put the app into a Nextcloud apps directory:
|
|
|
|
```bash
|
|
cd /path/to/nextcloud/apps-extra
|
|
git clone https://github.com/EDUCAlliance/talk-ai.git educai
|
|
cd educai
|
|
npm ci
|
|
npm run build
|
|
```
|
|
|
|
Enable the app:
|
|
|
|
```bash
|
|
cd /path/to/nextcloud
|
|
sudo -u www-data php occ app:enable educai
|
|
```
|
|
|
|
Run upgrade if Nextcloud reports pending migrations:
|
|
|
|
```bash
|
|
sudo -u www-data php occ upgrade --no-interaction
|
|
sudo -u www-data php occ migrations:status educai
|
|
```
|
|
|
|
## 2. Configure The Admin Settings
|
|
|
|
Open **Administration settings > Talk AI** and configure the required model settings:
|
|
|
|
- Primary API Endpoint
|
|
- Primary API Key
|
|
- Default Model
|
|
- Webhook Secret
|
|
|
|
Optional settings you can add later:
|
|
|
|
- secondary endpoint and fallback model
|
|
- allowed model list for per-bot model selection
|
|
- RAG and embedding endpoint
|
|
- Docling document conversion
|
|
- vision and speech endpoints
|
|
- rate limits
|
|
- MCP tools
|
|
|
|
Save settings before testing Talk.
|
|
|
|
## 3. Register The Talk Bot
|
|
|
|
Talk AI tries to register the shared `Talk AI` Talk bot when the app is enabled and when settings change. Check registration with:
|
|
|
|
```bash
|
|
sudo -u www-data php occ talk:bot:list
|
|
```
|
|
|
|
If the bot is missing, register it manually:
|
|
|
|
```bash
|
|
sudo -u www-data php occ talk:bot:install \
|
|
-f webhook,response \
|
|
"Talk AI" \
|
|
"your-webhook-secret" \
|
|
"https://your-nextcloud.example/index.php/apps/educai/webhook/talk"
|
|
```
|
|
|
|
The webhook URL must include `/index.php` on installations that route apps through that path. Disabling and re-enabling the app also re-runs the automatic registration.
|
|
|
|
## 4. Create A Bot
|
|
|
|
Open the Talk AI app and create a bot:
|
|
|
|
- choose a bot name
|
|
- choose a Talk mention such as `@supportbot`
|
|
- write the system prompt
|
|
- choose visibility: personal, groups, teams, or global
|
|
- choose a model if per-bot model selection is enabled
|
|
- enable RAG, tools, or a personal wiki if needed
|
|
|
|
Shared bots may start as drafts or pending approvals depending on the user's scope rights.
|
|
|
|
## 5. Activate Talk AI In A Talk Room
|
|
|
|
Open a Talk conversation and activate the shared `Talk AI` bot from the room settings or Smart Picker flow.
|
|
|
|
Then mention your app-level bot:
|
|
|
|
```text
|
|
@supportbot Can you summarize the project plan?
|
|
```
|
|
|
|
The shared Talk bot receives the webhook. Talk AI resolves `@supportbot`, checks access, runs the configured model and tools, and sends the answer back to Talk.
|
|
|
|
## 6. Check Logs
|
|
|
|
Watch Nextcloud logs while testing:
|
|
|
|
```bash
|
|
tail -f /path/to/nextcloud/data/nextcloud.log | grep -i educai
|
|
```
|
|
|
|
Common checks:
|
|
|
|
- `talk:bot:list` shows the shared Talk bot.
|
|
- The webhook URL contains `/index.php` when the installation needs it.
|
|
- The admin endpoint, key, and model are valid.
|
|
- The bot visibility allows the current user or room participants.
|
|
- Background jobs or `cron.php` run when testing RAG indexing.
|
|
|
|
See [Troubleshooting](./TROUBLESHOOTING.md) for deeper debugging.
|