Phi-3-mini-128k-instruct部署教程：Chainlit前端定制化（品牌LOGO/主题色）

Phi-3-mini-128k-instruct部署教程：Chainlit前端定制化（品牌LOGO/主题色）

想快速搭建一个属于自己的智能对话助手，并且能换上公司的Logo和主题色吗？今天，我们就来手把手教你，如何部署轻量又强大的Phi-3-mini-128k-instruct模型，并用Chainlit打造一个完全定制化的前端界面。

整个过程非常简单，不需要你懂复杂的AI框架，也不需要写很多前端代码。你只需要跟着步骤走，就能得到一个功能完整、界面美观的AI应用。无论是用于内部知识问答、客服原型，还是个人学习项目，都非常合适。

1. 准备工作：认识我们的工具

在开始动手之前，我们先花几分钟了解一下今天要用到的两个核心工具：Phi-3模型和Chainlit框架。了解它们能做什么，后面的操作就会清晰很多。

1.1 为什么选择Phi-3-mini-128k-instruct？

Phi-3-mini-128k-instruct是微软推出的一款“小身材，大能量”的AI模型。别看它只有38亿参数，在同类小模型中，它的表现非常出色。

它主要有以下几个特点，让它特别适合我们今天的场景：

• 轻量高效：模型体积小，这意味着它部署快，运行起来对电脑资源要求不高，响应速度也很快。
• 超长“记忆”：名字里的“128k”指的是它能处理的上下文长度。简单来说，就是它能记住并理解很长的一段对话或文档内容，不会聊着聊着就忘了前面说过什么。
• 指令理解强：经过专门的训练，它非常擅长理解并执行你的指令。你让它总结、翻译、写代码或者回答问题，它都能很好地完成。
• 完全开源：你可以自由地使用、修改和部署，没有任何商业使用的限制。

简单讲，它就像一个反应快、记性好、又听话的智能助手，而且部署成本很低。

1.2 Chainlit：快速搭建AI对话界面的神器

有了聪明的大脑（Phi-3模型），我们还需要一个好看的“脸”和用户交互。这就是Chainlit的作用。

Chainlit是一个专门为AI应用设计的开源框架，它的目标就是让开发者能像搭积木一样，快速构建出功能丰富的聊天界面。对我们来说，它最大的好处是：

• 几乎零前端代码：你不需要去写复杂的HTML、CSS、JavaScript，用Python就能定义界面和交互逻辑。
• 功能开箱即用：聊天窗口、消息流式显示、文件上传、历史记录管理这些功能，Chainlit都帮你做好了。
• 高度可定制：这也是本教程的重点——我们可以轻松地修改Logo、主题颜色、字体等，让界面完全符合你的品牌风格。

想象一下，Chainlit帮你建好了一个毛坯房（基础聊天室），而我们接下来要做的，就是按照你的喜好进行“精装修”（品牌定制）。

2. 核心部署：启动Phi-3模型服务

我们的第一步，是让Phi-3模型在后台运行起来，准备好接收问题并生成回答。这里我们使用vLLM作为推理引擎，它能极大地提升模型运行的速度。

2.1 一键启动模型服务

通常，模型服务已经预置在环境里了。你只需要打开终端，运行一条命令就能启动。命令看起来像这样：

python -m vllm.entrypoints.openai.api_server \\
–model /path/to/phi-3-mini-128k-instruct \\
–served-model-name phi-3-mini \\
–max-model-len 128000 \\
–api-key your-api-key-here \\
–port 8000

这条命令在做什么？

• –model: 告诉vLLM我们的Phi-3模型文件放在哪个文件夹。
• –served-model-name: 给服务起个名字，这里叫phi-3-mini。
• –max-model-len 128000: 这是最关键的一步，把模型的处理长度设置为128K，这样才能发挥它的长上下文优势。
• –api-key: 设置一个密码（API密钥），保护你的服务不被随便调用。
• –port 8000: 让服务在电脑的8000端口上运行。

运行成功后，你会看到终端输出一些日志，最后显示服务已经在http://localhost:8000上就绪了。

2.2 验证服务是否正常

服务启动后，我们怎么知道它真的在正常工作呢？有两个简单的方法：

方法一：查看日志 在终端或WebShell里，你可以查看服务的运行日志。如果看到包含“Uvicorn running on…”和“Model loaded”之类的信息，就说明模型加载成功，服务已经跑起来了。

方法二：发个测试请求 我们可以用最简单的curl命令，像敲门一样问一下服务是否在家。打开另一个终端窗口，输入：

curl http://localhost:8000/v1/models

如果一切正常，你会收到一个JSON格式的回复，里面列出了可用的模型名称（应该能看到phi-3-mini）。这就证明你的模型服务已经部署成功，正在8000端口等待指令。

3. 前端搭建：用Chainlit连接并定制界面

模型服务在后台默默运行，现在我们需要一个漂亮的窗口和它对话。这就是Chainlit出场的时候了。

3.1 创建并配置Chainlit应用

首先，我们需要创建一个Python文件，比如叫app.py。这个文件是整个前端应用的核心。

# app.py – Chainlit应用主文件
import chainlit as cl
import os
from openai import OpenAI

# 1. 配置模型服务地址和密钥
# 注意：这里的API密钥要和启动vLLM服务时设置的一致
MODEL_API_BASE = "http://localhost:8000/v1" # vLLM服务的地址
MODEL_API_KEY = "your-api-key-here" # 你的API密钥
MODEL_NAME = "phi-3-mini" # 模型服务名

# 初始化OpenAI客户端，但指向我们自己的vLLM服务
client = OpenAI(
base_url=MODEL_API_BASE,
api_key=MODEL_API_KEY
)

# 2. 处理用户消息的核心函数
@cl.on_message
async def main(message: cl.Message):
"""
每当用户发送一条消息，这个函数就会被调用。
它把消息发给Phi-3模型，并把模型的回复流式地显示给用户。
"""

# 创建一个空的回复对象，准备开始流式显示
msg = cl.Message(content="")
await msg.send()

# 调用我们部署的Phi-3模型
response = client.chat.completions.create(
model=MODEL_NAME,
messages=[
{"role": "system", "content": "你是一个乐于助人的AI助手。"},
{"role": "user", "content": message.content}
],
stream=True, # 启用流式输出，让回复一个字一个字地显示出来
max_tokens=2048,
temperature=0.7
)

# 流式处理模型的回复
for chunk in response:
if chunk.choices[0].delta.content is not None:
# 将模型生成的内容片段添加到消息中
await msg.stream_token(chunk.choices[0].delta.content)

# 流式传输完成，发送最终消息
await msg.update()

# 3. 应用启动时的设置
@cl.on_chat_start
async def start():
"""
当聊天会话开始时运行，可以在这里进行一些初始化。
"""
await cl.Message(content="你好！我是由Phi-3-mini驱动的AI助手，有什么可以帮你的吗？").send()

这个文件做了三件事：

3.2 启动你的聊天界面

保存好app.py文件后，在终端里运行它：

chainlit run app.py

稍等片刻，你的浏览器会自动打开一个标签页，地址是http://localhost:8000（如果8000被占了，可能是其他端口）。一个简洁的聊天界面就出现了！你可以直接在输入框里向Phi-3模型提问，体验它流畅的对话能力。

4. 品牌定制：换上你的Logo和主题色

现在到了最有趣的部分——个性化定制。默认的Chainlit界面很简洁，但我们可以让它变成你的专属风格。

所有的定制化配置，都通过一个叫chainlit.md的文件来完成。在app.py的同级目录下创建这个文件。

4.1 基础品牌信息设置

chainlit.md文件的开头部分，用于配置应用的基本信息：

# 欢迎使用我的AI助手

这是一个基于Phi-3-mini模型构建的智能对话助手。

## 功能特点
– 支持长达128K上下文的对话
– 响应迅速，理解能力强
– 界面简洁美观，支持深色/浅色模式
– 完全定制化的品牌形象

## 开始使用
直接在下方输入框提问即可，例如：
– “用Python写一个快速排序算法”
– “总结一下光合作用的过程”
– “帮我写一封会议邀请邮件”

这个文件顶部的#标题会成为网页的标题和主要的欢迎语。下面的内容会显示在聊天界面侧边栏的“欢迎”页签里，你可以在这里介绍应用的功能和使用方法。

4.2 核心定制：LOGO与主题色

接下来是重头戏，我们需要在app.py文件的开头部分（在import语句之后），通过Chainlit的设置函数来进行视觉定制。

重要提示：请将下面代码中的/path/to/your/logo.png替换为你自己的Logo图片路径。图片建议使用透明背景的PNG格式，尺寸大约为200×200像素，效果最佳。

# 在 app.py 的开头，import语句之后添加以下配置代码
@cl.set_chat_profiles
async def chat_profile():
"""
设置聊天配置，这里主要用于设置页面元数据，如Logo。
更细致的样式需要在 chainlit.config.py 或 chainlit.md 中设置。
"""
return [
cl.ChatProfile(
name="默认助手",
# 在这里可以设置不同聊天配置的图标，但全局Logo通常在别处设置
icon="2026-03-164ayvalthltm.png", # 示例：网络图标
),
]

# 更推荐的方式：使用环境变量或配置文件设置全局Logo
# 你可以创建一个 chainlit.config.py 文件，内容如下：
"""
import chainlit as cl

cl.set_logo("assets/logo.png") # 假设你的logo放在assets文件夹下
cl.set_title("我的品牌AI助手")
cl.set_author("你的公司或团队名")
"""

# 最简单直接的方式：在 chainlit.md 文件中使用HTML和CSS

由于Chainlit的版本和配置方式可能更新，最通用且强大的定制方法是在chainlit.md文件中使用HTML和CSS内联样式。在chainlit.md文件的末尾，我们可以添加一个<style>标签来覆盖所有样式：

<!– 在 chainlit.md 文件末尾添加 –>
<style>
/* 1. 设置品牌主色调 */
:root {
–primary: #4F46E5; /* 将这里的颜色代码改成你的品牌色，例如 #FF6B35 (橙色) */
–primary-dark: #4338CA;
–primary-light: #818CF8;
}

/* 2. 自定义Logo – 通过背景图方式 */
.cl-topbar {
/* 方法A：如果Logo是本地文件，需确保能被访问 */
/* background: url('/path/to/your/logo.png') no-repeat left 20px center !important; */
/* background-size: 40px 40px !important; */
/* padding-left: 70px !important; */

/* 方法B：更简单的方法，直接设置背景色和文字 */
background-color: var(–primary) !important;
}

.cl-topbar .cl-title {
color: white !important;
font-weight: 700;
/* 如果你想用文字代替Logo */
/* content: "我的品牌AI" !important; */
}

/* 3. 更改按钮和交互元素的颜色 */
.cl-button-primary {
background-color: var(–primary) !important;
border-color: var(–primary) !important;
}

.cl-button-primary:hover {
background-color: var(–primary-dark) !important;
}

/* 4. 更改用户和助手消息的气泡颜色 */
.cl-user-message {
border-left-color: var(–primary) !important;
}

.cl-assistant-message {
background-color: rgba(79, 70, 229, 0.05) !important; /* 主色调的浅色背景 */
}

/* 5. 更改输入框焦点状态 */
.cl-input:focus {
border-color: var(–primary) !important;
box-shadow: 0 0 0 2px rgba(79, 70, 229, 0.2) !important;
}

/* 6. 自定义字体（可选） */
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Microsoft YaHei', sans-serif !important;
}
</style>

如何操作：

4.3 应用定制效果

完成上述配置后，重启你的Chainlit应用：

# 如果之前已经在运行，先按 Ctrl+C 停止
chainlit run app.py

再次刷新浏览器，你会发现界面焕然一新：

• 顶部导航栏：变成了你设置的主题色。
• 所有按钮：悬浮、点击状态的颜色都统一成了品牌色。
• 消息气泡：用户消息的边框、助手消息的背景色都带有品牌色的痕迹。
• 整体感觉：从一个通用工具，变成了一个具有品牌辨识度的专属应用。

5. 进阶技巧与问题排查

基本的部署和定制完成后，你可能还想知道如何让它更好用，或者遇到问题怎么办。

5.1 提升使用体验的几个小技巧

• 修改系统提示词：在app.py的client.chat.completions.create函数里，有一个system角色的消息。你可以修改它的内容，来改变AI助手的“性格”和回答风格。比如改成“你是一个严谨的代码审查专家”或“你是一个幽默的讲故事高手”。
• 调整回答“创意度”：temperature参数控制回答的随机性。值越高（接近1.0），回答越创意、多样；值越低（接近0），回答越确定、保守。根据你的需求调整这个值。
• 启用对话历史：Chainlit默认会管理对话历史。你可以在侧边栏查看之前的对话记录，这对于长对话非常有用。

5.2 常见问题与解决方法

6. 总结

至此，我们已经完成了一个从模型部署到前端定制化的完整流程。让我们简单回顾一下：

这个组合的优势非常明显：Phi-3模型提供了优异的性能与性价比，而Chainlit则极大地降低了开发交互界面的门槛。你不需要是前端专家，也能打造出专业级的AI应用界面。

你可以在此基础上继续探索，比如：

• 为Chainlit添加文件上传功能，让AI可以读取并分析你的文档。
• 集成多个不同的模型，让用户可以在界面中选择使用。
• 将整个应用部署到服务器，分享给你的团队或客户使用。

希望这篇教程能帮助你快速搭建起属于自己的AI助手。动手试试吧，从换上第一个品牌色开始，感受创造的乐趣。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。