Fay: an avatar driven by asr/, llm/ and tts/, started with a shared key

asr/, llm/ and tts/ are three separate swap points

Fay's central design choice is visible in the directory names rather than in a configuration schema. asr/, llm/ and tts/ sit at the top level as siblings, so replacing one capability means swapping a module instead of rewriting a pipeline. The README states that digital human models, large language models through an OpenAI compatible interface, ASR and TTS models can be matched freely, which is the same claim the folder layout makes.

The dependency list narrows what that means in practice. azure-cognitiveservices-speech and aliyun-python-sdk-core are cloud speech clients, edge_tts reaches a Microsoft service, and langchain_openai plus langgraph carry the language model side. So the offline claim is a configuration decision rather than a property of the code. Pick local models in each of the three folders and the process runs without a network; leave the cloud clients in place and it does not.

python main.py start boots against a key the README calls slow

The quick start is one command, and it carries a hardcoded configuration identifier:

python main.py start -config_center d19f7b0a-2b8a-4503-8c0d-1a587b90eb69  #使用公共资源，速度非常慢，建议更换成自己的key

The trailing comment in that line is part of the documented command. It says the resource is shared, that the speed is very slow, and that you should substitute your own key. Expect to diagnose a slow start as an infrastructure problem before it is ever a code problem.

A hosted image is offered for people who do not want to install anything locally:

https://www.compshare.cn/images/compshareImage-1cft3sk9gvta?ytag=GPU_fay

That route moves the dependency problem to a third party, and it means the code you test is not the code on your machine.

Ubuntu needs portaudio before pyaudio will compile

Python 3.12 is the stated version, and Windows, macOS and Ubuntu are the stated systems. The Ubuntu case gets an explicit prerequisite block, because the audio stack is native:

sudo apt update
sudo apt install build-essential
sudo apt install portaudio19-dev

That matters because requirements.txt pins pyaudio at pyaudio~=0.2.11, which has no prebuilt wheel on every platform and falls back to compiling against portaudio. Install the dependencies after those packages, not before:

pip install -r requirements.txt

The same file pins websockets at about 10.4 and uvicorn below 0.35, so a shared virtual environment holding newer versions of either will be rewritten underneath you. Make a dedicated environment. A separate requirements-legacy.txt sits at the root, which suggests the pin set has already had to be revised once.

The admin page is Flask on port 5000, and PyQt5 is switched off

Configuration happens in a browser rather than in a settings dialog. After startup you open the management interface at:

http://127.0.0.1:5000

The Flask stack behind it is visible in requirements.txt: flask~=3.0.0, flask_cors~=3.0.10 and flask-httpauth, the last of which implies the interface is not unauthenticated. The README does not describe the credentials it expects.

There is a gui/ directory as well, and it is off by default: the PyQt5, PyQt5-sip and PyQtWebEngine lines in requirements.txt are all commented out. A desktop control surface exists in the tree and will not install from a plain requirements run. Two admin surfaces, one of them disabled, is a shape worth knowing before you build a deployment story on it.

qa.csv drives speech commands, scheduler/ drives silence

Two directories explain how the avatar behaves when nobody is talking to it. qa.csv at the repository root holds configurable voice commands, which is how a spoken phrase becomes an executed action without going through the language model at all. scheduler/ implements schedule-driven proactive conversation, and the README describes this as a digital human that starts talking on a timetable rather than in reply.

Alongside those, fay_player_knowledge/ carries the custom knowledge base, and the feature list also names custom question and answer pairs and configurable persona information. genagents/ and skills/ sit next to faymcp/ and mcp_servers/, with the README claiming MCP tool management over sse and studio.

The practical consequence is that the avatar's behaviour is data, not code. A wrong answer in production is probably a row in qa.csv or an entry in the persona config, and you need filesystem access to the deployment to find it.

MCP servers and the six interfaces the README never documents

The feature list names six interface categories: text interaction, voice interaction, digital human driving, management control, automatic broadcast and intent. That enumeration is the whole public contract in the repository. No paths, no request schemas and no payloads appear in the README, and no file at the top level looks like an API specification. The instructions for embedding Fay into your own product are a single wiki link with no accompanying text.

So the integration surface is real but unverified from the source tree. Anyone binding a microcontroller, app or website to this framework is signing up to read external documentation written outside the repository. For a component meant to sit inside a third-party business system, that is the wrong way round.

There is also no SECURITY.md at the root. A framework that drives avatars from LLM output and accepts network input has an obvious attack surface, and no file tells you where to report a problem in it.

No GitHub releases, and a wiki where the changelog should be

The repository has no GitHub releases at all. There is no tag to pin, no published artifact to download, and no semantic version to record in a deployment manifest. The last push was on 2026-09-21, so work is landing, but the only version signal in the whole tree is whatever requirements.txt happens to pin, and most of those lines are ranges rather than exact versions.

The changelog and the documentation both live on a Feishu wiki rather than in the docs/ directory the repository carries. That matters for a project whose stated audience includes developers outside China: the primary written record of what changed is behind a separate account on a separate platform, and it is not versioned alongside the code.

The repository is GPL-3.0, and the README pairs the open source claim with a commercial use disclaimer. The README's contact section also asks you to star the repository and follow a WeChat public account before handing over tutorials. Read the licence text yourself before shipping a build inside a product.

Editorial conclusion

Adopt Fay if you are building an interactive avatar for a kiosk, a course page or a third-party product and your language model already exposes an OpenAI compatible endpoint, since the README describes LLM support through an OpenAI compatible interface. Do not adopt it if you need a versioned, citable release or English documentation, because the repository has no GitHub releases and the changelog and docs are wiki links. Before anything else, replace the public config_center identifier in main.py start with your own, then confirm the model keys inside the renamed system.conf resolve, since the README warns that the shared one is slow.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. xszyou/Fay on GitHub