enh(Admin/AI): update background job worker docs

Signed-off-by: Anupam Kumar <[email protected]>

admin_manual/ai/app_assistant.rst

@@ -161,16 +161,7 @@ This field is appended to the block of chat messages, i.e. attached after the me
 The number of latest messages to consider for generating the next message. This does not include the user instructions, which is always considered in addition to this. This value should be adjusted in case you are hitting the token limit in your conversations too often.
 The AI text generation provider should ideally handle the max token limit case.
 
-Improve AI processing throughput
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Improve AI task pickup speed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Most AI tasks will be run as part of the background job system in Nextcloud which only runs jobs every 5 minutes by default.
-To pick up scheduled jobs faster you can set up background job workers that process AI tasks as soon as they are scheduled:
-
-run the following occ commands a daemon (you can also spawn multiple, for parallel processing):
-
-.. code-block::
-
- occ background-job:worker 'OC\TaskProcessing\SynchronousBackgroundJob'
-
-Make sure to restart these daemons regularly, for example once a day, to make sure the daemon runs the latest code.
+See :ref:`the relevant section in AI Overview<ai-overview_improve-ai-task-pickup-speed>` for more information.

admin_manual/ai/app_context_chat.rst

@@ -47,18 +47,32 @@ Installation
 
 0. Make sure the :ref:`Nextcloud Assistant app<ai-app-assistant>` is installed
 1. :ref:`Install AppAPI and setup a Deploy Demon<ai-app_api>`
-2. Install the *context_chat_backend* ExApp via the "External Apps" admin page in Nextcloud
+2. Install the *context_chat_backend* ExApp via the "External Apps" admin page in Nextcloud, or by executing
+
+.. code-block::
+
+ occ app_api:app:register context_chat_backend
+
 3. Install the *context_chat* app via the "Apps" page in Nextcloud, or by executing
 
 .. code-block::
 
  occ app:enable context_chat
 
-4. Optionally, run two instances of this occ command for faster processing of requests:
+4. Install a text generation backend like *llm2* (via the "External Apps" page in Nextcloud) or *integration_openai* (via the "Apps" page in Nextcloud), or by executing
+
+.. code-block::
+
+ occ app_api:app:register llm2
+
+or
 
 .. code-block::
 
- occ background-job:worker 'OC\TaskProcessing\SynchronousBackgroundJob'
+ occ app:enable integration_openai
+
+
+5. Optionally but recommended, setup background workers for faster pickup of tasks. See :ref:`the relevant section in AI Overview<ai-overview_improve-ai-task-pickup-speed>` for more information.
 
 **Note**: Both apps need to be installed and both major version and minor version of the two apps must match for the functionality to work (ie. "v1.3.4" and "v1.3.1"; but not "v1.3.4" and "v2.1.6"; and not "v1.3.4" and "v1.4.5"). Keep this in mind when updating.
 
@@ -69,15 +83,15 @@ Context chat will automatically load user data into the Vector DB using backgrou
 
 .. code-block::
 
- occ background-job:worker 'OCA\ContextChat\BackgroundJobs\StorageCrawlJob'
+ occ background-job:worker -t 60 'OCA\ContextChat\BackgroundJobs\StorageCrawlJob'
 
 .. code-block::
 
- occ background-job:worker 'OCA\ContextChat\BackgroundJobs\IndexerJob'
+ occ background-job:worker -t 60 'OCA\ContextChat\BackgroundJobs\IndexerJob'
 
 This will ensure that the necessary background jobs are run as often as possible: ``StorageCrawlJob`` will crawl Nextcloud storages and put files that it finds into a queue and ``IndexerJob`` will iterate over the queue and load the file content into the Vector DB.
 
-Make sure to restart these daemons regularly. For example once a day.
+See :ref:`the task speedup section in AI Overview<ai-overview_improve-ai-task-pickup-speed>` to know better ways to run these jobs.
 
 Scaling
 -------

admin_manual/ai/overview.rst

@@ -175,6 +175,80 @@ Apps can integrate their content with Context Chat to make it available for quer
 * *files*
 * `Analytics <https://apps.nextcloud.com/apps/analytics>`_
 
+.. _ai-overview_improve-ai-task-pickup-speed:
+
+Improve AI task pickup speed
+----------------------------
+
+Most AI tasks will be run as part of the background job system in Nextcloud which only runs jobs every 5 minutes by default.
+To pick up scheduled jobs faster you can set up background job workers that process AI tasks as soon as they are scheduled.
+
+For screen or tmux session
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run the following occ command inside a screen or a tmux session, preferably 4 or more times for parallel processing of multiple requests by different or the same user (and as a requirement for some apps like context_chat).
+It would be best to run one command per screen session or per tmux pane to keep the logs visible and the worker easily restartable.
+
+.. code-block::
+
+ set -e; while true; do sudo -u www-data occ background-job:worker -v -t 60 "OC\TaskProcessing\SynchronousBackgroundJob"; done
+
+You may want to adjust the number of workers and the timeout to your needs. The above command will run with a timeout of 60 seconds which means any changes to the settings or the code will be picked up after 60 seconds (worst case scenario). This timeout does not, in any way, affect the processing or the timeout of the AI tasks.
+The logs of the worker can be checked by attaching to the screen or tmux session.
+
+For systemd service
+~~~~~~~~~~~~~~~~~~~
+
+1. Create a systemd service file in ``/etc/systemd/system/[email protected]`` with the following content:
+
+.. code-block::
+
+ [Unit]
+ Description=Nextcloud AI worker %i
+ After=network.target
+
+ [Service]
+ ExecStart=/opt/nextcloud-ai-worker/taskprocessing.sh %i
+ Restart=always
+
+ [Install]
+ WantedBy=multi-user.target
+
+2. Create a shell script in ``/opt/nextcloud-ai-worker/taskprocessing.sh`` with the following content and make sure to make it executable:
+
+.. code-block::
+
+ #!/bin/sh
+ echo "Starting Nextcloud AI Worker $1"
+ sudo -u www-data php occ background-job:worker -t 60 'OC\TaskProcessing\SynchronousBackgroundJob'
+
+Same as above, you may want to adjust the number of workers and the timeout to your needs. The above command will run with a timeout of 60 seconds which means any changes to the settings or the code will be picked up after 60 seconds (worst case scenario). This timeout does not, in any way, affect the processing or the timeout of the AI tasks.
+
+3. Enable and start the service 4 or more times:
+
+.. code-block::
+
+ for i in {1..4}; do systemctl enable --now nextcloud-ai-worker@$i.service; done
+
+The status of the workers can be checked with (replace 1 with the worker number):
+
+.. code-block::
+
+ systemctl status [email protected]
+
+The list of workers can be checked with:
+
+.. code-block::
+
+ systemctl list-units --type=service | grep nextcloud-ai-worker
+
+The complete logs of the workers can be checked with (replace 1 with the worker number):
+
+.. code-block::
+
+ journalctl -xeu [email protected]
+
+
 Frequently Asked Questions
 --------------------------