Welcome to the Omi backend setup guide! Omi is an innovative, multimodal AI assistant that combines cutting-edge technologies to provide a seamless user experience. This guide will help you set up the backend infrastructure that powers Omi’s intelligent capabilities.
Before you start, make sure you have the following:
Note: If you are not very experienced in backend development, we recommend installing Homebrew (for macOS or Linux) or Chocolatey (for Windows).
Install Google Cloud SDK:
brew install google-cloud-sdk
choco install gcloudsdk
Enable Necessary APIs: 🔧
Authenticate with Google Cloud: 🔐
<project-id>
with your Google Cloud project ID:
application_default_credentials.json
file in the ~/.config/gcloud
directory. This file is used for automatic authentication with Google Cloud services in Python.Install Python & Dependencies: 🐍
brew install python
choco install python
brew install git ffmpeg
choco install git.install ffmpeg
brew install opus
pip install PyOgg
brew install -r requirements.txt
Clone the Backend Repository: 📂
Set up Pusher Service: 📡 [Optional]
.env.template
file and rename it to .env
:
SERVICE_ACCOUNT_JSON
environment variable in the .env
file to the string representation of your Google Cloud service account credentials (google-credentials.json
). This is used to authenticate with Google CloudSet up Typesense: 🔎 [Optional]
memories
and use the schema provided in the typesense/memories.schema
fileusers/{userId}/memories
structured,transcript_segments,created_at,deleted,discarded,started_at,id,finished_at,geolocation,userId
typesense_sync
collection and add a document named backfill
with data {'trigger' : true}
(required only if you already have memories in Firestore and want to sync them to Typesense)TYPESENSE_HOST
, TYPESENSE_HOST_PORT
and TYPESENSE_API_KEY
environment variables in the .env
file to the host URL and API key provided by TypesenseSet up the Environment File: 📝
.env.template
file and rename it to .env
:
.env
file and fill in the following:
123
) for local development.env.template
provides a default key suitable for local development (e.g., omi_ZwB2ZNqB2HHpMK6wStk7sTpavJiPTFg7gXUHnc4tFABPU6pZ2c2DKgehtfgi4RZv
). For production, you must generate a new secure key.True
to disable the socket timeout for the backend server (socket will stay connected for as long as the app is open)Install Python Dependencies: 📚 You have two options for installing the required Python packages:
Option A: Using a Virtual Environment (Recommended) 🐍
(venv)
at the beginning of your command prompt, indicating that the virtual environment is activeOption B: Direct Installation
Code Formatting: 💅
black
for formatting with a line length of 120 characters.black
installed:
Set up Ngrok for Tunneling: 🚇
8000
(the default port for the backend). For example:
https://example.ngrok-free.app
) that points to your local backendStart the Backend Server: 🖥️
--reload
automatically restarts the server when code changes are saved, making development easier--env-file .env
loads environment variables from your .env
file--host 0.0.0.0
listens to every interface on your computer so you don’t have to set up ngrok
when developing in your network--port 8000
port for backend to listenTroubleshooting SSL Errors: 🔒
utils/stt/vad.py
:
.env
file. Ensure there are no trailing spacesConnect the App to the Backend: 🔗
API_BASE_URL
to the public URL provided by Ngrok (e.g., https://example.ngrok-free.app/
) (don’t forget the trailing / )Now, your Omi app should be successfully connected to the locally running backend.
source venv/bin/activate
on macOS/Linux or venv\Scripts\activate
on Windows)Here’s a detailed explanation of each environment variable you need to define in your .env
file:
HUGGINGFACE_TOKEN
: Your Hugging Face Hub API token, used to download models for speech processing (like voice activity detection)BUCKET_SPEECH_PROFILES
: The name of the Google Cloud Storage bucket where user speech profiles are storedBUCKET_PLUGIN_LOGOS
: The name of the Google Cloud Storage bucket where to put logos for uploaded appsBUCKET_BACKUPS
: The name of the Google Cloud Storage bucket used for backups (if applicable)GOOGLE_APPLICATION_CREDENTIALS
: The path to your Google Cloud service account credentials file (google-credentials.json
). This is generated in step 3 of I. Setting Up Google Cloud & Firebase
google-credentials.json
in the same directory where the application is runningapplication_default_credentials.json
file (e.g., ~/.config/gcloud/application_default_credentials.json
on macOS/Linux or %APPDATA%\gcloud\application_default_credentials.json
on Windows)PINECONE_API_KEY
: Your Pinecone API key, used for vector database operations. Storing Memory Embeddings: Each memory is converted into a numerical representation (embedding). Pinecone efficiently stores these embeddings and allows Omi to quickly find the most relevant memories related to a user’s queryPINECONE_INDEX_NAME
: The name of your Pinecone index where memory embeddings are storedREDIS_DB_HOST
: The host address of your Redis instanceREDIS_DB_PORT
: The port number of your Redis instanceREDIS_DB_PASSWORD
: The password for your Redis instance (blank by default)DEEPGRAM_API_KEY
: Your Deepgram API key, used for real-time and pre-recorded audio transcriptionADMIN_KEY
: A temporary key used for authentication during local development (replace with a more secure method in production)OPENAI_API_KEY
: Your OpenAI API key, used for accessing OpenAI’s language models for chat, memory processing, and moreENCRYPTION_SECRET
: A secret key used to encrypt sensitive user data, such as conversations, memories, and chat messages. The key must be at least 32 bytes long. The .env.template
file includes a default key (e.g., omi_ZwB2ZNqB2HHpMK6wStk7sTpavJiPTFg7gXUHnc4tFABPU6pZ2c2DKgehtfgi4RZv
) which is sufficient for local development. For a production environment, it is crucial to replace this with your own securely generated random string.GITHUB_TOKEN
: Your GitHub personal access token, used to access GitHub’s API for retrieving the latest firmware versionWORKFLOW_API_KEY
: Your custom API key for securing communication with external workflows or integrationsHOSTED_PUSHER_API_URL
: URL of your omi-pusher service if you’re using one. Example: http://omi-push:8081TYPESENSE_HOST
: URL of your typesense server.TYPESENSE_API_KEY
: Typesense API keyMake sure to replace the placeholders (<api-key>
, <bucket-name>
, etc.) with your actual values.
We welcome contributions from the open source community! Whether it’s improving documentation, adding new features, or reporting bugs, your input is valuable. Check out our Contribution Guide for more information.
If you’re stuck, have questions, or just want to chat about Omi:
Happy coding! 💻 If you have any questions or need further assistance, don’t hesitate to reach out to our community.