From 48425cc82f41c43f47454365ca3eb05ab929518b Mon Sep 17 00:00:00 2001 From: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com> Date: Tue, 21 Jul 2026 17:03:17 -0500 Subject: [PATCH] docs fixes --- docs/docs/configuration/advanced/reference.md | 14 +- docs/docs/configuration/advanced/system.md | 2 +- docs/docs/configuration/config.md | 3 +- .../state_classification.md | 6 +- docs/docs/configuration/genai/config.md | 144 +++++++++++------- docs/docs/configuration/genai/objects.md | 7 +- docs/docs/configuration/live.md | 2 +- docs/docs/configuration/semantic_search.md | 4 +- docs/docs/integrations/home-assistant.md | 2 +- docs/docs/integrations/mqtt.md | 2 +- 10 files changed, 118 insertions(+), 68 deletions(-) diff --git a/docs/docs/configuration/advanced/reference.md b/docs/docs/configuration/advanced/reference.md index 896ab2642b..827be1aa94 100644 --- a/docs/docs/configuration/advanced/reference.md +++ b/docs/docs/configuration/advanced/reference.md @@ -171,13 +171,14 @@ model: # Valid values are rgb, bgr, or yuv. (default: shown below) input_pixel_format: rgb # Required: Object detection model input tensor format - # Valid values are nhwc or nchw (default: shown below) + # Valid values are nhwc, nchw, hwnc, or hwcn (default: shown below) input_tensor: nhwc # Optional: Data type of the model input tensor # Valid values are float, float_denorm, or int (default: shown below) input_dtype: int - # Required: Object detection model type, currently only used with the OpenVINO detector - # Valid values are ssd, yolox, yolonas (default: shown below) + # Required: Object detection model architecture, used by detectors that support more + # than one model type (openvino, onnx, rknn, memryx, axengine, synaptics, and others) + # Valid values are ssd, yolox, yolonas, yolo-generic, rfdetr, dfine (default: shown below) model_type: ssd # Required: Label name modifications. These are merged into the standard labelmap. labelmap: @@ -468,8 +469,8 @@ review: detections: False # Optional: Activity Context Prompt to give context to the GenAI what activity is and is not suspicious. # It is important to be direct and detailed. See documentation for the default prompt structure. - activity_context_prompt: """Define what is and is not suspicious -""" + activity_context_prompt: | + Define what is and is not suspicious # Optional: Image source for GenAI (default: preview) # Options: "preview" (uses cached preview frames at ~180p) or "recordings" (extracts frames from recordings at 480p) # Using "recordings" provides better image quality but uses more tokens per image. @@ -813,7 +814,8 @@ classification: cameras: camera_name: # Required: Crop of image frame on this camera to run classification on - crop: [0, 180, 220, 400] + # [x1, y1, x2, y2] as decimals between 0 and 1, relative to the detect resolution + crop: [0.0, 0.25, 0.3, 0.85] # Optional: If classification should be run when motion is detected in the crop (default: shown below) motion: False # Optional: Interval to run classification on in seconds (default: shown below) diff --git a/docs/docs/configuration/advanced/system.md b/docs/docs/configuration/advanced/system.md index 28291efff7..c1ab568352 100644 --- a/docs/docs/configuration/advanced/system.md +++ b/docs/docs/configuration/advanced/system.md @@ -335,7 +335,7 @@ For example: ``` services: frigate: - image: blakeblackshear/frigate:latest + image: ghcr.io/blakeblackshear/frigate:stable environment: - FRIGATE_BASE_PATH=/frigate ``` diff --git a/docs/docs/configuration/config.md b/docs/docs/configuration/config.md index edb6d0cd74..971de7e84b 100644 --- a/docs/docs/configuration/config.md +++ b/docs/docs/configuration/config.md @@ -130,7 +130,8 @@ go2rtc: ```yaml genai: - api_key: "{FRIGATE_GENAI_API_KEY}" + my_provider: + api_key: "{FRIGATE_GENAI_API_KEY}" ``` ## Common configuration examples diff --git a/docs/docs/configuration/custom_classification/state_classification.md b/docs/docs/configuration/custom_classification/state_classification.md index 7d479946bf..aea4742537 100644 --- a/docs/docs/configuration/custom_classification/state_classification.md +++ b/docs/docs/configuration/custom_classification/state_classification.md @@ -73,9 +73,13 @@ classification: interval: 10 # also run every N seconds (optional) cameras: front: - crop: [0, 180, 220, 400] + # [x1, y1, x2, y2] as decimals between 0 and 1, relative to the + # camera's detect resolution + crop: [0.0, 0.25, 0.3, 0.85] ``` +Crop coordinates are normalized: each value is a fraction of the camera's `detect` width or height, not a pixel value. Drawing the crop in the UI wizard writes these values for you. + An optional config, `save_attempts`, can be set as a key under the model name. This defines the number of classification attempts to save in the Recent Classifications tab. For state classification models, the default is 100. diff --git a/docs/docs/configuration/genai/config.md b/docs/docs/configuration/genai/config.md index d1da92c05f..5b5fe7edfb 100644 --- a/docs/docs/configuration/genai/config.md +++ b/docs/docs/configuration/genai/config.md @@ -9,9 +9,40 @@ import NavPath from "@site/src/components/NavPath"; ## Configuration -A Generative AI provider can be configured in the global config, which will make the Generative AI features available for use. There are currently 4 native providers available to integrate with Frigate. Other providers that support the OpenAI standard API can also be used. See the OpenAI-Compatible section below. +A Generative AI provider can be configured in the global config, which will make the Generative AI features available for use. There are currently 5 native providers available to integrate with Frigate. Other providers that support the OpenAI standard API can also be used. See the OpenAI-Compatible section below. -To use Generative AI, you must define a single provider at the global level of your Frigate configuration. If the provider you choose requires an API key, you may either directly paste it in your configuration, or store it in an environment variable prefixed with `FRIGATE_`. +`genai` is a map of named providers. Each key under `genai` is a name you choose, and its value is that provider's settings: + +```yaml +genai: + my_provider: # any name you like + provider: ollama + base_url: http://localhost:11434 + model: qwen3-vl:4b +``` + +The examples on this page all use `my_provider`, but the name is arbitrary and is only used to reference the provider elsewhere in the config (for example, `semantic_search.model`). + +Each provider handles one or more **roles**: `chat`, `descriptions`, and `embeddings`. A provider handles all three by default, and each role may be assigned to exactly one provider. Define a single provider if you want it to do everything, or split the roles across several providers using the `roles` option: + +```yaml +genai: + local: + provider: ollama + base_url: http://localhost:11434 + model: qwen3-vl:4b + roles: + - descriptions + - embeddings + cloud: + provider: gemini + api_key: "{FRIGATE_GEMINI_API_KEY}" + model: gemini-2.5-flash + roles: + - chat +``` + +If the provider you choose requires an API key, you may either directly paste it in your configuration, or store it in an environment variable prefixed with `FRIGATE_`. ## Local Providers @@ -85,11 +116,12 @@ All llama.cpp native options can be passed through `provider_options`, including ```yaml genai: - provider: llamacpp - base_url: http://localhost:8080 - model: your-model-name - provider_options: - context_size: 16000 # Optional, overrides the context size reported by the server. + my_provider: + provider: llamacpp + base_url: http://localhost:8080 + model: your-model-name + provider_options: + context_size: 16000 # Optional, overrides the context size reported by the server. ``` @@ -129,13 +161,14 @@ Note that Frigate will not automatically download the model you specify in your ```yaml genai: - provider: ollama - base_url: http://localhost:11434 - model: qwen3-vl:4b - provider_options: # other Ollama client options can be defined - keep_alive: -1 - options: - num_ctx: 8192 # make sure the context matches other services that are using ollama + my_provider: + provider: ollama + base_url: http://localhost:11434 + model: qwen3-vl:4b + provider_options: # other Ollama client options can be defined + keep_alive: -1 + options: + num_ctx: 8192 # make sure the context matches other services that are using ollama ``` @@ -151,11 +184,12 @@ For OpenAI-compatible servers (such as llama.cpp) that don't expose the configur ```yaml genai: - provider: openai - base_url: http://your-llama-server - model: your-model-name - provider_options: - context_size: 8192 # Specify the configured context size + my_provider: + provider: openai + base_url: http://your-llama-server + model: your-model-name + provider_options: + context_size: 8192 # Specify the configured context size ``` This ensures Frigate uses the correct context window size when generating prompts. @@ -178,10 +212,11 @@ This ensures Frigate uses the correct context window size when generating prompt ```yaml genai: - provider: openai - base_url: http://your-server:port - api_key: your-api-key # May not be required for local servers - model: your-model-name + my_provider: + provider: openai + base_url: http://your-server:port + api_key: your-api-key # May not be required for local servers + model: your-model-name ``` @@ -219,19 +254,21 @@ Ollama also supports [cloud models](https://ollama.com/cloud), where model infer ```yaml genai: - provider: ollama - base_url: http://localhost:11434 - model: cloud-model-name + my_provider: + provider: ollama + base_url: http://localhost:11434 + model: cloud-model-name ``` or when using Ollama Cloud directly ```yaml genai: - provider: ollama - base_url: https://ollama.com - model: cloud-model-name - api_key: your-api-key + my_provider: + provider: ollama + base_url: https://ollama.com + model: cloud-model-name + api_key: your-api-key ``` @@ -269,9 +306,10 @@ To start using Gemini, you must first get an API key from [Google AI Studio](htt ```yaml genai: - provider: gemini - api_key: "{FRIGATE_GEMINI_API_KEY}" - model: gemini-2.5-flash + my_provider: + provider: gemini + api_key: "{FRIGATE_GEMINI_API_KEY}" + model: gemini-2.5-flash ``` @@ -281,12 +319,13 @@ genai: To use a different Gemini-compatible API endpoint, set the `provider_options` with the `base_url` key to your provider's API URL. For example: -```yaml {4,5} +```yaml {5,6} genai: - provider: gemini - ... - provider_options: - base_url: https://... + my_provider: + provider: gemini + ... + provider_options: + base_url: https://... ``` Other HTTP options are available, see the [python-genai documentation](https://github.com/googleapis/python-genai). @@ -320,9 +359,10 @@ To start using OpenAI, you must first [create an API key](https://platform.opena ```yaml genai: - provider: openai - api_key: "{FRIGATE_OPENAI_API_KEY}" - model: gpt-4o + my_provider: + provider: openai + api_key: "{FRIGATE_OPENAI_API_KEY}" + model: gpt-4o ``` @@ -338,13 +378,14 @@ To use a different OpenAI-compatible API endpoint, set the `OPENAI_BASE_URL` env For OpenAI-compatible servers (such as llama.cpp) that don't expose the configured context size in the API response, you can manually specify the context size in `provider_options`: -```yaml {5,6} +```yaml {6,7} genai: - provider: openai - base_url: http://your-llama-server - model: your-model-name - provider_options: - context_size: 8192 # Specify the configured context size + my_provider: + provider: openai + base_url: http://your-llama-server + model: your-model-name + provider_options: + context_size: 8192 # Specify the configured context size ``` This ensures Frigate uses the correct context window size when generating prompts. @@ -379,10 +420,11 @@ To start using Azure OpenAI, you must first [create a resource](https://learn.mi ```yaml genai: - provider: azure_openai - base_url: https://instance.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview - model: gpt-5-mini - api_key: "{FRIGATE_OPENAI_API_KEY}" + my_provider: + provider: azure_openai + base_url: https://instance.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview + model: gpt-5-mini + api_key: "{FRIGATE_OPENAI_API_KEY}" ``` diff --git a/docs/docs/configuration/genai/objects.md b/docs/docs/configuration/genai/objects.md index eb8dadef53..7ad8004abe 100644 --- a/docs/docs/configuration/genai/objects.md +++ b/docs/docs/configuration/genai/objects.md @@ -52,9 +52,10 @@ You can define custom prompts at the global level and per-object type. To config ```yaml genai: - provider: ollama - base_url: http://localhost:11434 - model: qwen3-vl:8b-instruct + my_provider: + provider: ollama + base_url: http://localhost:11434 + model: qwen3-vl:8b-instruct objects: genai: diff --git a/docs/docs/configuration/live.md b/docs/docs/configuration/live.md index 5df70844c9..de10255e30 100644 --- a/docs/docs/configuration/live.md +++ b/docs/docs/configuration/live.md @@ -196,7 +196,7 @@ services: ::: -See [go2rtc WebRTC docs](https://github.com/AlexxIT/go2rtc/tree/v1.8.3#module-webrtc) for more information about this. +See [go2rtc WebRTC docs](https://github.com/AlexxIT/go2rtc/tree/v1.9.14#module-webrtc) for more information about this. ### Two way talk diff --git a/docs/docs/configuration/semantic_search.md b/docs/docs/configuration/semantic_search.md index c58b634fd8..30a60d505f 100644 --- a/docs/docs/configuration/semantic_search.md +++ b/docs/docs/configuration/semantic_search.md @@ -163,8 +163,8 @@ genai: model: your-model-name roles: - embeddings - - vision - - tools + - descriptions + - chat semantic_search: enabled: True diff --git a/docs/docs/integrations/home-assistant.md b/docs/docs/integrations/home-assistant.md index dd7d548047..f5ca05f1a4 100644 --- a/docs/docs/integrations/home-assistant.md +++ b/docs/docs/integrations/home-assistant.md @@ -281,7 +281,7 @@ For advanced usecases, this behavior can be changed with the [RTSP URL template](#options) option. When set, this string will override the default stream address that is derived from the default behavior described above. This option supports [jinja2 templates](https://jinja.palletsprojects.com/) and has the `camera` dict -variables from [Frigate API](../integrations/api) +variables from [Frigate API](/integrations/api/frigate-http-api) available for the template. Note that no Home Assistant state is available to the template, only the camera dict from Frigate. diff --git a/docs/docs/integrations/mqtt.md b/docs/docs/integrations/mqtt.md index e929ade300..775adef3ea 100644 --- a/docs/docs/integrations/mqtt.md +++ b/docs/docs/integrations/mqtt.md @@ -16,7 +16,7 @@ MQTT requires a network connection to your broker. This is typically local, but ### `frigate/available` Designed to be used as an availability topic with Home Assistant. Possible message are: -"online": published when Frigate is running (on startup) +"online": published once Frigate is running and has published its initial state. Note that this is published on every connection to the broker, so it is republished if the broker restarts or the connection drops and recovers, without Frigate itself restarting. "stopped": published when Frigate is stopped normally "offline": published automatically by the MQTT broker if Frigate disconnects unexpectedly (via MQTT Will Message)