Fay Agent 实操指南：5步跑通一个会自主决策的数字人

Fay Agent 实操指南：5步跑通一个会自主决策的数字人

【免费下载链接】Fayfay是一个帮助数字人（2.5d、3d、移动、pc、网页）或大语言模型（openai兼容、deepseek）连通业务系统的agent框架。项目地址: https://gitcode.com/GitHub_Trending/fay/Fay

有人问你"北京今天多少度"，你卡住了：要空出群聊去查，还得兼顾回答明天的安排。你想要的是一个听得懂、会自己判断该调哪个工具、还会主动记事的数字人。Fay Agent，就是面向数字人和大语言模型的开源agent框架，干的就是这件事。

快速上手：从克隆到第一次对话的5步

第1步，克隆代码

git clone -b fay-agent-edition https://gitcode.com/GitHub_Trending/fay/Fay

主仓库只是总览页，带货版、助理版、agent版分别在自己的分支上，这步直接把agent版拉下来。

第2步，装依赖

cd Fay pip install -r requirements.txt

这步装齐语音识别、语音合成、大模型调用要用的Python依赖，一次性装完。

第3步，把模型密钥写进配置

打开项目里的config.json，填上模型API密钥和服务地址。Fay只对接OpenAI兼容接口（说白了，就是说OpenAI那套接口语言的所有模型服务），DeepSeek、Moonshot填法都一样。

第4步，启动服务

python main.py

这一步把整个后端拉起来：模型连接、语音识别、网页面板一起加载。

第5步，打开面板验证

跑完后，终端会看到服务启动成功的提示，浏览器打开面板，数字人已经在那儿等你。输入"你能做什么"，它列出一串可执行的能力，就算部署完成了。

Fay Agent 三个核心玩法

它怎么自己决定调工具

普通聊天模型只能在自己知识范围内答题，答不上来就编。Fay Agent给模型配了"一双手"：你问"北京今天天气怎么样"，agent先判断该调天气检索工具，拿到结果再转成人话。2024年3月补上的python执行器、网页检索工具也是同一套逻辑，让它替你跑代码、抓网页内容。想接自己的业务工具，照着现有工具的写法注册一个函数就行。

怎么让它主动找你说话

多数数字人是"你问一句、它答一句"。Fay Agent带了个面板发消息工具，配合日程功能，可以在事件临近时主动向聊天面板推一条提醒。2024年3月的版本还加了主动发微信消息的实验工具，agent版能主动联系主人，不在面板前也能收到。

换个底座模型只改一行配置

因为只对接OpenAI兼容接口，换模型不用动代码：DeepSeek、Moonshot，或者用vLLM（给本地大模型加速推理的工具）部署的本地模型，把配置里的模型地址和密钥改掉就能跑。agent版上线后底座换过好几次，每次都是这么改的。

它到底怎么跑：一次对话的数据流 🔄

说白了，整条链路是个没有固定脚本的循环：你说的话先过ASR（语音转文字那步），文本连同最近的对话历史一起发给大模型；模型对照工具清单决定"调不调、调哪个"；要调，工具结果就塞回给模型，由它生成最终回复；最后TTS（文字变声音那步）把回复念出来，数字人开口。不用工具时就直接回答。"要不要调工具"由模型自己拍板，这就是agent的"自主"所在。

参数调优：3个容易忽略的配置

改"历史记录条数"控制上下文：agent每次对话前会读最近的历史记录，读得越多上下文越足，token也涨得越凶。在配置里把这个条数改成10，日常助理足够；长期挂着的部署可以再调小，省token。

开热词：funasr（语音识别组件）支持热词识别。业务里的专有名词、产品编码经常听错，把它们加进热词表，识别准确率明显上去。

代理字段留空：配置里有gpt代理设置。不用代理就留空，别填杂值。旧版本有些base_url在空值下会报错，升级到较新分支就没这个问题了。

这里有个坑：这三处都在同一个配置文件里，但服务不会实时重读，改完要重启main.py才生效。

落地场景：谁在用它干什么

门店门口的导购数字人：店主把产品手册的PDF接进知识库检索工具，顾客在柜台前问"这款支不支持WiFi 6"，agent从手册里查到答案念出来，店员不用每个问题都跑一趟。

开发者的UE5 metahuman：接上metahuman-stream工程后，说一句"帮我查一下后台页面昨天的单量"，agent去抓页面、跑处理、把数字念回来，数字人从"会说话的"变成"会干活的"。

小团队的日程提醒：团队把agent接进会议日程，开会前一晚agent主动向面板推提醒，出差在外的成员没刷群也收到了改期通知。

新手避坑：最容易遇到的3个问题 ⚠️

• 语音开头几个字被吞：个别TTS合成链路的已知问题，新版已修复；升级代码或换合成服务商（阿里云TTS、Azure TTS都支持）。
• 历史记录为空时报错：agent版早期代码在消息初始化和空历史两个场景下有这个bug，2024年7月已修复，拉最新代码重启即可。
• 服务启动后改不了面板配置：这是刻意限制，防止运行中配置不一致；先停服务，改完配置再启动。

先跑通main.py的启动链路，确认数字人会说会答，再动手加自己的业务工具，顺手把历史条数和TTS配置调成合适的值。

【免费下载链接】Fayfay是一个帮助数字人（2.5d、3d、移动、pc、网页）或大语言模型（openai兼容、deepseek）连通业务系统的agent框架。项目地址: https://gitcode.com/GitHub_Trending/fay/Fay