1. 项目概述
今天我要分享一个非常实用的本地AI聊天应用搭建方案，只需要Python、Chainlit和Ollama三个工具，就能在本地电脑上快速搭建一个功能完善的AI聊天界面。这个方案特别适合想要在本地测试不同大语言模型，或者想搭建私人AI助手的开发者。
这个项目最大的优势在于：
- 完全本地运行，无需联网或依赖云服务
- 支持多种大语言模型自由切换
- 实现类似ChatGPT的流式输出效果
- 界面美观，操作简单
- 代码量极少（不到100行）
2. 环境准备
2.1 安装Ollama
Ollama是一个开源的本地大语言模型运行环境，支持多种主流模型。安装步骤如下：
- 访问Ollama官网(https://ollama.com/download)下载对应操作系统的安装包
- 运行安装程序（Windows双击exe，Mac拖拽到Applications）
- 安装完成后，打开终端/命令行验证安装：
bash复制ollama --version
看到版本号输出表示安装成功。
注意：Ollama安装后会自动启动后台服务，默认监听11434端口。如果服务没有自动启动，可以手动运行
ollama serve命令启动。
2.2 下载模型
Ollama本身不包含任何模型，需要手动下载。以下是几个推荐模型及其特点：
- 通义千问2.5系列（中文表现优秀）：
bash复制ollama pull qwen2.5 # 标准版
ollama pull qwen2.5:7b # 轻量版
- Llama3系列（英文表现优秀）：
bash复制ollama pull llama3 # 标准版(8B)
ollama pull llama3:8b # 明确指定8B版本
- 其他可选模型：
bash复制ollama pull gemma2 # Google的轻量模型
ollama pull phi3 # 微软的小型模型
下载完成后，可以通过以下命令查看已安装模型：
bash复制ollama list
2.3 Python环境准备
建议使用Python 3.8或更高版本。创建一个新的虚拟环境：
bash复制python -m venv ollama-env
source ollama-env/bin/activate # Linux/Mac
ollama-env\Scripts\activate # Windows
安装所需依赖：
bash复制pip install chainlit httpx
3. 核心代码解析
3.1 获取本地模型列表
python复制def get_ollama_models():
try:
with httpx.Client(timeout=10.0) as client:
response = client.get("http://localhost:11434/api/tags")
response.raise_for_status()
data = response.json()
return [m["name"] for m in data["models"]]
except Exception as e:
print(f"获取模型列表失败: {e}")
return []
这段代码通过调用Ollama的API接口获取本地安装的所有模型列表。关键点：
- 使用httpx库发送HTTP请求
- 超时设置为10秒防止长时间等待
- 异常处理确保程序健壮性
- 从返回的JSON数据中提取模型名称
3.2 过滤生成型模型
python复制GENERATIVE_MODELS = [
m for m in OLLAMA_MODELS
if "embed" not in m.lower() and "bge" not in m.lower()
]
这里使用列表推导式过滤掉embedding模型（通常用于文本向量化而非生成），只保留适合聊天的生成型模型。
3.3 流式聊天实现
python复制async def ollama_chat_stream(model: str, messages: list):
payload = {
"model": model,
"messages": messages,
"stream": True
}
async with httpx.AsyncClient(timeout=None) as client:
try:
async with client.stream("POST", "http://localhost:11434/api/chat", json=payload) as response:
async for line in response.aiter_lines():
if not line.strip():
continue
data = json.loads(line)
if "message" in data and "content" in data["message"]:
yield data["message"]["content"]
if data.get("done"):
break
except Exception as e:
yield f"\n\n[错误: 调用 Ollama 失败 - {str(e)}]"
这是实现流式输出的核心函数：
- 使用async/await实现异步调用
- 设置stream=True开启流式传输
- 逐行读取响应内容并yield返回
- 包含完整的错误处理逻辑
3.4 Chainlit界面实现
Chainlit的三个核心装饰器：
@cl.on_chat_start- 聊天会话开始时触发
python复制@cl.on_chat_start
async def on_chat_start():
# 显示欢迎信息和模型列表
# 设置默认模型
# 如果有多个模型，显示切换按钮
@cl.on_message- 处理用户消息
python复制@cl.on_message
async def on_message(message: cl.Message):
# 获取当前模型
# 构建消息历史
# 调用ollama_chat_stream获取回复
# 流式显示回复内容
@cl.action_callback- 处理按钮点击
python复制@cl.action_callback("model_select")
async def on_model_select(action: cl.Action):
# 切换当前模型
# 更新界面显示
4. 项目运行与使用
4.1 启动应用
确保Ollama服务正在运行后，执行：
bash复制chainlit run app.py -w
-w参数启用自动刷新功能，开发时非常实用。启动后浏览器会自动打开http://localhost:8000。
4.2 界面功能说明
- 欢迎界面：显示检测到的所有模型和可用生成模型
- 模型切换：如果有多个生成模型，会显示切换按钮
- 聊天区域：下方输入消息，上方显示对话历史
- 流式输出：回复会像ChatGPT一样逐字显示
4.3 开发技巧
- 调试模式：添加
--debug参数可以看到更多日志
bash复制chainlit run app.py -w --debug
- 自定义端口：如果8000端口被占用，可以指定其他端口
bash复制chainlit run app.py -w --port 8001
- 界面定制：Chainlit支持通过
config.py文件自定义界面
python复制# config.py
config = {
"theme": "light",
"title": "我的AI助手"
}
5. 常见问题解决
5.1 模型相关问题
问题：模型列表为空或缺少生成模型
- 确认已正确下载模型（
ollama list） - 检查Ollama服务是否正常运行（
ollama serve） - 确保没有防火墙阻止11434端口
问题：模型响应慢
- 尝试使用更小的模型版本（如7B而不是13B）
- 检查电脑资源使用情况（CPU/GPU/内存）
- 关闭其他占用资源的程序
5.2 运行环境问题
问题：Chainlit无法启动
- 确认Python版本≥3.8
- 检查依赖是否安装正确（
pip list） - 尝试重新创建虚拟环境
问题：浏览器没有自动打开
- 手动访问http://localhost:8000
- 检查
-w参数是否正确添加 - 确保没有其他程序占用8000端口
5.3 代码调试技巧
- 添加打印语句检查关键变量：
python复制print(f"当前模型: {model_name}")
print(f"消息历史: {messages}")
- 使用try-catch捕获异常：
python复制try:
# 可能出错的代码
except Exception as e:
print(f"错误详情: {str(e)}")
- 逐步注释代码定位问题
6. 项目扩展思路
6.1 功能增强
- 添加系统提示词：让AI扮演特定角色
python复制messages = [
{"role": "system", "content": "你是一个专业的Python程序员助手"},
{"role": "user", "content": message.content}
]
- 支持文件上传：让AI处理文档内容
python复制@cl.on_file_upload
async def on_file_upload(file: cl.File):
content = file.read().decode("utf-8")
await cl.Message(f"已上传文件内容:\n\n{content}").send()
- 添加记忆功能：持久化保存聊天历史
python复制import pickle
# 保存
with open("history.pkl", "wb") as f:
pickle.dump(messages, f)
# 读取
with open("history.pkl", "rb") as f:
messages = pickle.load(f)
6.2 性能优化
- 模型预热：在聊天开始前预加载模型
python复制async def warmup_model(model_name):
async with httpx.AsyncClient() as client:
await client.post("http://localhost:11434/api/generate", json={
"model": model_name,
"prompt": "ping",
"stream": False
})
- 响应缓存：对常见问题缓存回复
python复制from functools import lru_cache
@lru_cache(maxsize=100)
def get_cached_response(prompt):
# 调用模型获取回复
return response
- 并行请求：同时处理多个用户消息
python复制import asyncio
async def handle_multiple_messages(messages):
tasks = [ollama_chat_stream(model, [msg]) for msg in messages]
return await asyncio.gather(*tasks)
6.3 部署方案
- Docker化：方便在不同环境部署
dockerfile复制FROM python:3.9
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["chainlit", "run", "app.py"]
- 反向代理：通过Nginx暴露服务
nginx复制server {
listen 80;
server_name ai.example.com;
location / {
proxy_pass http://localhost:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
- API化：提供REST接口供其他应用调用
python复制from fastapi import FastAPI
app = FastAPI()
@app.post("/chat")
async def chat_endpoint(message: str):
# 调用Ollama处理消息
return {"response": response}
在实际使用中，我发现这个方案特别适合快速验证不同模型的表现。通过简单的模型切换，可以直观比较不同模型在相同问题上的回答差异。比如测试中文理解能力时，通义千问通常比Llama3表现更好；而处理英文技术问题时，Llama3往往更胜一筹。
一个实用技巧是在代码中添加模型性能监控：
python复制import time
start_time = time.time()
async for token in ollama_chat_stream(model_name, messages):
# ...
end_time = time.time()
print(f"模型响应时间: {end_time - start_time:.2f}秒")
这样可以帮助选择最适合本地硬件配置的模型版本。在我的测试中，7B参数模型在普通笔记本电脑上就能流畅运行，而更大的模型可能需要更强的硬件支持。