> ## Documentation Index
> Fetch the complete documentation index at: https://extended-openai-conversation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Frequently asked questions from the community

## Installation & Setup

<AccordionGroup>
  <Accordion title="How do I configure Azure OpenAI?">
    For a full walkthrough, see the [Installation guide](/installation#azure-openai).

    1. Go to [Azure AI Foundry](https://ai.azure.com/) → **My Assets** → **Models + endpoints**
    2. Select your deployed model, then open the **Code** tab
    3. Copy these values from the code example:
       * `azure_endpoint` → use as **Base URL** (e.g. `https://yourname.cognitiveservices.azure.com/`)
       * `api_version` → use as **API Version** (e.g. `2024-12-01-preview`)
       * API key shown in the example → use as **API Key**
    4. In HA, set **API Provider** to `Azure OpenAI` and paste the values above
    5. Enable **Skip Authentication**
    6. In the assistant options, enter the **deployment name** as the model name

    <Note>
      Azure API Management domains (`azure-api.net`, `services.ai.azure.com`) are also supported in addition to `cognitiveservices.azure.com`.
    </Note>

    To debug connectivity issues, add `openai: debug` to your HA logger config to see the exact URL being called.
  </Accordion>

  <Accordion title="Can I use Ollama or other local LLMs?">
    For a full walkthrough, see the [Installation guide](/installation#other-compatible-servers).

    Yes. Use the `/v1` endpoint and enable **Skip Authentication**:

    | Field               | Value                     |
    | ------------------- | ------------------------- |
    | API Provider        | `OpenAI`                  |
    | Base URL            | `http://<HOST>:11434/v1`  |
    | API Key             | Any value (e.g. `ollama`) |
    | Skip Authentication | **On**                    |

    <Warning>
      The `/v1` suffix in the Base URL is required. Using `http://<HOST>:11434` without `/v1` causes a 404 error.
    </Warning>

    **Function calling support:** Many local models do not reliably call tools. If the assistant verbally acknowledges your request but nothing actually happens, use a model with explicit tool-use support such as `qwen2.5:14b` or `llama3.1:8b`, and add this to your system prompt:

    ```
    When you want to take action, you MUST use the execute_services function.
    You must wrap your commands in a list array.
    ```
  </Accordion>
</AccordionGroup>

## Device Control

<AccordionGroup>
  <Accordion title="The assistant talks about actions but never executes them">
    Several things can cause this:

    1. **Entities not exposed** — Go to **Settings** → **Voice Assistants** → **Expose entities** and make sure the relevant entities are toggled on.

    2. **Model doesn't support function/tool calling** — Local models especially may not emit structured tool calls. Try other models, or add explicit instructions to the system prompt.
  </Accordion>

  <Accordion title="The AI can't find my entity or uses the wrong service name">
    * **Entity not exposed:** Confirm the entity is enabled under **Settings** → **Voice Assistants** → **Expose entities**.

    * **Wrong service name:** LLMs sometimes invent service names. There are two ways to guide the model toward the correct service:

      **Option 1 — Text instruction in the system prompt:**

      ```
      To open a cover, use the service cover.open_cover (not cover.open).
      ```

      **Option 2 — Provide a concrete example in the system prompt:**

      Showing the AI a full working example is often more effective than a text rule alone. For instance, to teach it how to start a timer correctly:

      ```
      Example of starting a timer:
      - domain: timer
        service: start
        service_data:
          entity_id: timer.kitchen
          duration: "00:05:00"
      ```

      The model will follow the pattern from the example rather than guessing the service name.

    * **Missing area context:** Help the AI understand room assignments by adding `area_name()` to the entities CSV in your prompt:
      ```
      {{ entity.entity_id }},{{ entity.name }},{{ entity.state }},{{ area_name(entity.entity_id) }}
      ```
  </Accordion>

  <Accordion title="I get a 'max_tokens is not supported with this model' error">
    Newer OpenAI models (o1, o3, gpt-4.5, gpt-5, etc.) replaced `max_tokens` with `max_completion_tokens`. This was fixed in **v2.0.0**. Upgrade via HACS.
  </Accordion>

  <Accordion title="I get a context length exceeded error">
    You have too many tokens in the request. Options:

    1. **Reduce exposed entities** — Go to **Settings** → **Voice Assistants** → **Expose entities** and only expose what the AI actually needs to control.
    2. **Filter function output** — If a function (e.g. weather forecast) returns large data, use a template to filter the result before returning it to the model.
    3. **Reduce the number of functions** — Each function definition (its name, description, and parameter schema) is included in every request and counts toward the token limit. Remove functions you don't actively use.
  </Accordion>
</AccordionGroup>

## Advanced Usage

<AccordionGroup>
  <Accordion title="How do I give the assistant web search access?">
    The OpenAI API does not include browsing by default. Add a web search function using the [Google Custom Search API](https://developers.google.com/custom-search/v1/overview):

    ````yaml theme={null}
    - spec:
        name: search_google
        description: Search Google using the Custom Search API.
        parameters:
          type: object
          properties:
            query:
              type: string
              description: The search query.
          required:
          - query
      function:
        type: rest
        resource_template: "https://www.googleapis.com/customsearch/v1?key=[GOOGLE_API_KEY]&cx=[GOOGLE_PROGRAMMING_SEARCH_ENGINE]:omuauf_lfve&q={{ query }}&num=3"
        value_template: >-
          {% if value_json["items"] %}
          ```csv
          title,link
          {% for item in value_json["items"] %}
          "{{ item.title | replace(',', ' ') }}","{{ item.link }}"
          {% endfor %}
          ```
          {% else %}
          No results found,
          {% endif %}
    ````

    Also update your system prompt to allow the assistant to answer general questions beyond home control.
  </Accordion>

  <Accordion title="Local LLM echoes my prompt or outputs weird tokens like <|recipient|>">
    This means the local model does not properly support OpenAI-compatible function/tool calling. It is outputting raw chat template tokens instead of structured tool calls.

    **Solutions:**

    * Switch to a model with explicit tool-use support
    * For basic chat only (no device control), remove all functions from the configuration.
  </Accordion>
</AccordionGroup>

## Debugging

<AccordionGroup>
  <Accordion title="How do I enable debug logging?">
    Add the following to your `configuration.yaml`:

    ```yaml theme={null}
    logger:
      logs:
        custom_components.extended_openai_conversation: debug
    ```

    To also see the raw payloads sent to the LLM:

    ```yaml theme={null}
    logger:
      logs:
        custom_components.extended_openai_conversation: debug
        openai: debug
    ```

    In the HA Logs UI (**Settings** → **System** → **Logs**), click **Load Full Logs** — the filtered view at the top only shows errors by default.
  </Accordion>
</AccordionGroup>

***

<Note>
  Don't see your question here? Search the [GitHub Issues](https://github.com/jekalmin/extended_openai_conversation/issues) or open a new one.
</Note>