Os LLMs personalizados permitem que você use sua própria chave de API da OpenAI ou execute um servidor LLM totalmente personalizado.

Visão geral

Por padrão, usamos nossas próprias credenciais internas para modelos populares como o OpenAI. Para usar um servidor LLM personalizado, ele precisa seguir uma das seguintes estruturas de solicitação/resposta compatíveis com OpenAI:

• API Chat Completions (/v1/chat/completions)
• API Responses (/v1/responses)

Os guias a seguir abordam os dois casos de uso:

1. Use sua própria chave da OpenAI: use sua própria chave de API da OpenAI com nossa plataforma.
2. Servidor LLM personalizado: hospede e conecte sua própria implementação de servidor LLM.

Você aprenderá a:

• Armazenar sua chave de API da OpenAI na ElevenLabs
• Hospedar um servidor que replique o endpoint Chat Completions ou Responses da OpenAI
• Direcionar a ElevenLabs ao seu endpoint personalizado
• Transmitir parâmetros extras ao seu LLM conforme necessário

Resumo do raciocínio

Seu endpoint precisa retornar o raciocínio separadamente da resposta final. A ElevenLabs não gera o raciocínio a partir da resposta final.

Para solicitar raciocínio de um endpoint compatível, ative Resumo do raciocínio nas configurações de LLM do agente ou defina enable_reasoning_summary pela API.

Retornar raciocínio

Use o formato correspondente ao seu endpoint:

Consulte Resumo do raciocínio para saber sobre armazenamento, entrega e limitações.

Usando sua própria chave da OpenAI

Para integrar uma chave personalizada da OpenAI, atualize as configurações do seu agente no painel da ElevenLabs para apontar para seu servidor LLM personalizado e crie um segredo com sua OPENAI_API_KEY:

Servidor LLM personalizado

Para usar um servidor LLM personalizado, configure um endpoint de servidor compatível usando o padrão da OpenAI. Você pode implementar a API Chat Completions (/v1/chat/completions) ou a API Responses (/v1/responses).

Ambos os endpoints precisam retornar respostas no formato SSE (Server-Sent Events) com Content-Type: text/event-stream.

import json
import os
import fastapi
from fastapi.responses import StreamingResponse
from openai import AsyncOpenAI
import uvicorn
import logging
from dotenv import load_dotenv
from pydantic import BaseModel
from typing import List, Optional
# Load environment variables from .env file
load_dotenv()
# Retrieve API key from environment
OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')
if not OPENAI_API_KEY:
    raise ValueError("OPENAI_API_KEY not found in environment variables")
app = fastapi.FastAPI()
oai_client = AsyncOpenAI(api_key=OPENAI_API_KEY)
class Message(BaseModel):
    role: str
    content: str
class ChatCompletionRequest(BaseModel):
    messages: List[Message]
    model: str
    temperature: Optional[float] = 0.7
    max_tokens: Optional[int] = None
    stream: Optional[bool] = False
    user_id: Optional[str] = None
@app.post("/v1/chat/completions")
async def create_chat_completion(request: ChatCompletionRequest) -> StreamingResponse:
    oai_request = request.dict(exclude_none=True)
    if "user_id" in oai_request:
        oai_request["user"] = oai_request.pop("user_id")
    chat_completion_coroutine = await oai_client.chat.completions.create(**oai_request)
    async def event_stream():
        try:
            async for chunk in chat_completion_coroutine:
                # Convert the ChatCompletionChunk to a dictionary before JSON serialization
                chunk_dict = chunk.model_dump()
                yield f"data: {json.dumps(chunk_dict)}\n\n"
            yield "data: [DONE]\n\n"
        except Exception as e:
            logging.error("An error occurred: %s", str(e))
            yield f"data: {json.dumps({'error': 'Internal error occurred!'})}\n\n"
    return StreamingResponse(event_stream(), media_type="text/event-stream")
if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8013)

Execute este código ou o código do seu próprio servidor.

Configurando uma URL pública para seu servidor

Para tornar seu servidor acessível, crie uma URL pública usando uma ferramenta de tunelamento como o ngrok:

ngrok http --url=<Your url>.ngrok.app 8013

Configurando o CustomLLM da ElevenLabs

Em seguida, atualize as configurações do seu agente no painel da ElevenLabs para apontar para seu servidor LLM personalizado.

Direcione a URL do seu servidor para o endpoint do ngrok e defina “Limit token usage” como 5000.

Agora você pode começar a interagir com seu agente usando seu próprio servidor LLM.

Otimização para LLMs com processamento lento

Se o seu LLM personalizado tem tempos de processamento lentos (talvez devido a raciocínio agêntico ou requisitos de pré-processamento), você pode melhorar o fluxo da conversa implementando palavras de preenchimento nas suas respostas de streaming. Essa técnica ajuda a manter a prosódia natural da fala enquanto seu LLM gera a resposta completa.

Palavras de preenchimento

Quando seu LLM precisar de mais tempo para processar a resposta completa, retorne uma resposta inicial terminando com "... " (reticências seguidas de um espaço). Isso permite que o sistema Text to Speech mantenha um fluxo natural e preserve o dinamismo da conversa. Isso cria pausas naturais que se conectam bem ao conteúdo subsequente, sobre o qual o LLM pode raciocinar por mais tempo. O espaço extra é fundamental para garantir que o conteúdo subsequente não seja anexado a "...", o que pode causar distorções no áudio.

Implementação

Veja como modificar seu servidor de LLM personalizado para implementar palavras de preenchimento:

@app.post("/v1/chat/completions")
async def create_chat_completion(request: ChatCompletionRequest) -> StreamingResponse:
    oai_request = request.dict(exclude_none=True)
    if "user_id" in oai_request:
        oai_request["user"] = oai_request.pop("user_id")
    async def event_stream():
        try:
            # Send initial buffer chunk while processing
            initial_chunk = {
                "id": "chatcmpl-buffer",
                "object": "chat.completion.chunk",
                "created": 1234567890,
                "model": request.model,
                "choices": [{
                    "delta": {"content": "Let me think about that... "},
                    "index": 0,
                    "finish_reason": None
                }]
            }
            yield f"data: {json.dumps(initial_chunk)}\n\n"
            # Process the actual LLM response
            chat_completion_coroutine = await oai_client.chat.completions.create(**oai_request)
            async for chunk in chat_completion_coroutine:
                chunk_dict = chunk.model_dump()
                yield f"data: {json.dumps(chunk_dict)}\n\n"
            yield "data: [DONE]\n\n"
        except Exception as e:
            logging.error("An error occurred: %s", str(e))
            yield f"data: {json.dumps({'error': 'Internal error occurred!'})}\n\n"
    return StreamingResponse(event_stream(), media_type="text/event-stream")

Integração com ferramentas do sistema

Seu LLM personalizado pode acionar ferramentas do sistema para controlar o fluxo e o estado da conversa. Essas ferramentas são incluídas automaticamente no parâmetro tools das suas solicitações de conclusão de chat quando configuradas no seu agente.

Como as ferramentas do sistema funcionam

1. Decisão do LLM: seu LLM personalizado decide quando chamar essas ferramentas com base no contexto da conversa
2. Resposta da ferramenta: o LLM responde com chamadas de função no formato padrão da OpenAI
3. Processamento de backend: a ElevenLabs processa as chamadas de ferramenta e atualiza o estado da conversa

Para mais informações sobre as ferramentas do sistema, consulte nosso guia

Ferramentas do sistema disponíveis

{
  "type": "function",
  "function": {
    "name": "end_call",
    "arguments": "{\"reason\": \"Task completed successfully\", \"message\": \"Thank you for using our service. Have a great day!\"}"
  }
}

{
  "type": "function",
  "function": {
    "name": "language_detection",
    "arguments": "{\"reason\": \"User requested Spanish\", \"language\": \"es\"}"
  }
}

{
  "type": "function",
  "function": {
    "name": "transfer_to_agent",
    "arguments": "{\"reason\": \"User needs billing support\", \"agent_number\": 0}"
  }
}

{
  "type": "function",
  "function": {
    "name": "transfer_to_number",
    "arguments": "{\"reason\": \"Complex billing issue\", \"transfer_number\": \"+15551234567\", \"client_message\": \"I'm transferring you to a billing specialist who can help with your account.\", \"agent_message\": \"Customer has a complex billing dispute about order #12345 from last month.\"}"
  }
}

{
  "type": "function",
  "function": {
    "name": "skip_turn",
    "arguments": "{\"reason\": \"User requested time to think\"}"
  }
}

{
  "type": "function",
  "function": {
    "name": "voicemail_detection",
    "arguments": "{\"reason\": \"Automated greeting detected with request to leave message\"}"
  }
}

Exemplo de solicitação com ferramentas do sistema

Quando as ferramentas do sistema estão configuradas, seu LLM personalizado receberá solicitações que incluem as ferramentas no formato padrão da OpenAI:

{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant. You have access to system tools for managing conversations."
    },
    {
      "role": "user",
      "content": "I think we're done here, thanks for your help!"
    }
  ],
  "model": "your-custom-model",
  "temperature": 0.7,
  "max_tokens": 1000,
  "stream": true,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "end_call",
        "description": "Call this function to end the current conversation when the main task has been completed...",
        "parameters": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "The reason for the tool call."
            },
            "message": {
              "type": "string",
              "description": "A farewell message to send to the user along right before ending the call."
            }
          },
          "required": ["reason"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "language_detection",
        "description": "Change the conversation language when the user expresses a language preference explicitly...",
        "parameters": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "The reason for the tool call."
            },
            "language": {
              "type": "string",
              "description": "The language to switch to. Must be one of language codes in tool description."
            }
          },
          "required": ["reason", "language"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "skip_turn",
        "description": "Skip a turn when the user explicitly indicates they need a moment to think...",
        "parameters": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Optional free-form reason explaining why the pause is needed."
            }
          },
          "required": []
        }
      }
    }
  ]
}

Recursos adicionais

from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
extra_body_for_convai = {
    "UUID": "123e4567-e89b-12d3-a456-426614174000",
    "parameter-1": "value-1",
    "parameter-2": "value-2",
}
config = ConversationInitiationData(
    extra_body=extra_body_for_convai,
)

import json
import os
import fastapi
from fastapi.responses import StreamingResponse
from fastapi import Request
from openai import AsyncOpenAI
import uvicorn
import logging
from dotenv import load_dotenv
from pydantic import BaseModel
from typing import List, Optional
# Load environment variables from .env file
load_dotenv()
# Retrieve API key from environment
OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')
if not OPENAI_API_KEY:
    raise ValueError("OPENAI_API_KEY not found in environment variables")
app = fastapi.FastAPI()
oai_client = AsyncOpenAI(api_key=OPENAI_API_KEY)
class Message(BaseModel):
    role: str
    content: str
class ChatCompletionRequest(BaseModel):
    messages: List[Message]
    model: str
    temperature: Optional[float] = 0.7
    max_tokens: Optional[int] = None
    stream: Optional[bool] = False
    user_id: Optional[str] = None
    elevenlabs_extra_body: Optional[dict] = None
@app.post("/v1/chat/completions")
async def create_chat_completion(request: ChatCompletionRequest) -> StreamingResponse:
    oai_request = request.dict(exclude_none=True)
    print(oai_request)
    if "user_id" in oai_request:
        oai_request["user"] = oai_request.pop("user_id")
    if "elevenlabs_extra_body" in oai_request:
        oai_request.pop("elevenlabs_extra_body")
    chat_completion_coroutine = await oai_client.chat.completions.create(**oai_request)
    async def event_stream():
        try:
            async for chunk in chat_completion_coroutine:
                chunk_dict = chunk.model_dump()
                yield f"data: {json.dumps(chunk_dict)}\n\n"
            yield "data: [DONE]\n\n"
        except Exception as e:
            logging.error("An error occurred: %s", str(e))
            yield f"data: {json.dumps({'error': 'Internal error occurred!'})}\n\n"
    return StreamingResponse(event_stream(), media_type="text/event-stream")
if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8013)

{
  "messages": [
    {
      "role": "system",
      "content": "\n  <Redacted>"
    },
    {
      "role": "assistant",
      "content": "Hey I'm currently unavailable."
    },
    {
      "role": "user",
      "content": "Hey, who are you?"
    }
  ],
  "model": "gpt-4o",
  "temperature": 0.5,
  "max_tokens": 5000,
  "stream": true,
  "elevenlabs_extra_body": {
    "UUID": "123e4567-e89b-12d3-a456-426614174000",
    "parameter-1": "value-1",
    "parameter-2": "value-2"
  }
}