# ChatAI **Repository Path**: xiaomao12/chat-ai ## Basic Information - **Project Name**: ChatAI - **Description**: AI对话聊天 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-20 - **Last Updated**: 2026-05-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ChatAI 一个基于 **Vue 3 + Vite + TypeScript + Element Plus** 的 AI 对话客户端，支持多模型配置、本地配置管理、流式输出、Markdown 渲染、代码高亮、消息重发/重新生成等功能。 适合用于： - OpenAI 兼容接口聊天 - DeepSeek / 通义 / Moonshot / OpenRouter / 本地大模型网关接入 - 个人 AI 工具箱 - 内部知识助手前端壳 - 自定义模型调试与参数测试 --- ## 1. 项目用途 本项目是一个前端 AI 聊天界面，核心目标是提供一个： - 界面清爽 - 配置灵活 - 支持流式响应 - 支持 Markdown / 代码展示 - 支持多套模型配置切换 - 适合二次开发 的通用 AI 聊天客户端。 你可以把它当成： 1. 一个开箱即用的 AI 聊天页面 2. 一个 OpenAI 兼容接口调试工具 3. 一个适合企业内部继续扩展的前端基础项目 --- ## 2. 项目技术栈 ### 前端框架 - **Vue 3**：核心前端框架 - **TypeScript**：提供类型约束，提升可维护性 - **Vite**：开发与打包工具，启动快、构建快 ### UI 与交互 - **Element Plus**：界面组件库 - **@element-plus/icons-vue**：图标库 - **Sass / SCSS**：样式编写 ### 状态与路由 - **Pinia**：状态管理 - **Vue Router**：路由管理 ### 内容渲染 - **markdown-it**：Markdown 渲染 - **highlight.js**：代码高亮 - **clipboard-copy**：复制文本/代码 --- ## 3. 当前功能特性 ### 对话能力 - 支持普通聊天 - 支持流式输出 - 支持停止生成 - 支持删除单条消息 - 支持重发用户消息 - 支持重新生成 AI 回复 - 支持清空当前会话 ### Markdown 能力 - 支持 Markdown 渲染 - 支持代码块高亮 - 支持复制代码 - 支持表格、列表、引用块等基础展示 - 可自动识别部分代码 / SQL / JSON 内容并按代码块展示 ### 配置能力 - 支持配置： - BaseURL - API Key - 模型名称 - Temperature - max_tokens - 上下文轮数 - 是否流式输出 - System Prompt - 支持保存当前配置 - 支持另存为新配置 - 支持重命名配置 - 支持删除配置 - 支持快速切换不同模型配置 - 配置自动保存到本地 --- ## 4. 目录结构说明 ```text README.md . ├─ src │ ├─ components # 组件，如聊天面板、消息项、配置面板等 │ ├─ services # 请求服务层 │ ├─ stores # Pinia 状态管理 │ ├─ utils # 通用工具、Markdown 处理等 │ ├─ views # 页面视图 │ ├─ constants # 默认配置常量 │ └─ types # 类型定义 ├─ public # 静态资源 ├─ package.json # 项目依赖与脚本 └─ vite.config.* # Vite 配置 ``` --- ## 5. 环境要求 建议环境： - **Node.js >= 18** - **npm >= 9** 或 **pnpm >= 8** 可使用以下命令查看版本： ```bash README.md node -v npm -v ``` --- ## 6. 安装与启动 ### 6.1 克隆项目 ```bash README.md git clone <你的仓库地址> cd <项目目录> ``` ### 6.2 安装依赖 使用 npm： ```bash README.md npm install ``` 如果你使用 pnpm： ```bash README.md pnpm install ``` ### 6.3 本地开发启动 ```bash README.md npm run dev ``` 启动后通常会输出本地地址，例如： ```text README.md http://localhost:5173/ ``` 用浏览器打开即可。 --- ## 7. 打包与预览 ### 7.1 生产打包 ```bash README.md npm run build ``` 打包完成后会生成： ```text README.md dist/ ``` 这个目录就是可以部署的静态文件。 ### 7.2 本地预览打包结果 ```bash README.md npm run preview ``` ### 7.3 类型检查 ```bash README.md npm run type-check ``` --- ## 8. 部署方式 本项目是纯前端静态站点，打包后的 `dist` 目录可直接部署到： - Nginx - Apache - 宝塔静态站点 - Vercel - Netlify - Gitee Pages - GitHub Pages - 任意对象存储静态托管 ### 8.1 前端直连部署说明 当前项目默认是 **浏览器直接请求模型接口**，因此部署时需要确认： - 目标模型服务支持浏览器访问 - 目标接口允许跨域（CORS） - API Key 可以在前端环境中使用 如果你的模型平台不允许前端直连，或者你不希望在浏览器中暴露 Key，建议使用后端代理方式，见下文 **第 9 章**。 ### 8.2 Nginx 示例 ```nginx README.md server { listen 80; server_name your-domain.com; root /path/to/dist; index index.html; location / { try_files $uri $uri/ /index.html; } } ``` > 如果你使用的是 history 路由模式，`try_files` 很重要。 ### 8.3 静态托管平台部署 如果你部署到 Vercel / Netlify / Gitee Pages / GitHub Pages，一般流程为： 1. 连接仓库 2. 安装依赖 3. 执行打包命令：`npm run build` 4. 发布目录填写：`dist` --- ## 9. 推荐的生产接入方式 如果你只是个人本地使用，可以直接前端填写 BaseURL 与 API Key。 如果你准备上线给多人使用，推荐使用： ```text README.md 浏览器前端 -> 你的后端服务 -> 模型平台 ``` 这样做的好处： - 不暴露真实 API Key - 可统一控制模型与参数白名单 - 可做登录鉴权 - 可做调用日志与审计 - 可做限流、计费、配额控制 ### 9.1 推荐后端代理职责 后端代理通常负责： - 保存真实 API Key - 接收前端请求 - 转发到模型服务商 - 过滤危险参数 - 记录请求日志 - 处理跨域 ### 9.2 代理接口设计建议 前端可以固定请求你自己的接口，例如： ```text README.md POST /api/chat/completions ``` 由后端再转发到： ```text README.md https://api.openai.com/v1/chat/completions ``` 或者其他兼容平台。 ### 9.3 BaseURL 配置建议 如果你使用自己的后端代理，那么前端配置里的 BaseURL 建议填写成： ```text README.md https://your-domain.com/api http://127.0.0.1:8080/api ``` 这样前端就不会直接暴露第三方模型平台地址和真实密钥。 --- ## 10. 界面说明与截图占位 你可以在本节补充项目截图，方便他人快速理解功能布局。 建议补充以下截图： 1. 主聊天界面 2. AI 配置弹窗 3. 多配置切换示意 4. Markdown / 代码高亮展示 5. 移动端布局截图 示例写法： ```markdown README.md ## 主界面截图 ![主界面](./docs/images/chat-home.png) ## 配置弹窗截图 ![配置弹窗](./docs/images/config-dialog.png) ``` 建议在仓库中建立目录： ```text README.md docs/ └─ images/ ``` 用于统一存放 README 插图。 --- ## 11. 如何使用 ### 9.1 第一次进入项目 进入页面后，先打开右侧/顶部的 **AI 配置弹窗**，填写基础参数： - BaseURL - API Key - 模型名称 填写后会自动保存到本地。 ### 9.2 开始聊天 配置正确后： 1. 在输入框输入问题 2. 点击发送 3. 等待 AI 返回 4. 如开启流式输出，会逐步显示内容 ### 9.3 切换配置 你可以保存多套模型配置，比如： - DeepSeek 开发环境 - OpenAI GPT-4o - 本地 Ollama 网关 - 测试环境模型 保存后可在配置列表中快速切换。 --- ## 12. 配置项详细说明 下面是弹窗中各项参数的详细解释。 ### 12.1 接口基础地址 BaseURL 模型接口的基础地址。 示例： ```text README.md https://api.openai.com https://api.deepseek.com http://127.0.0.1:11434 ``` 注意： - 必须是 `http://` 或 `https://` - 本项目会校验地址是否合法 - 不同平台地址不同，请参考对应服务商文档 --- ### 12.2 API 密钥 调用模型接口所需的认证密钥。 说明： - 一般由模型服务平台提供 - 会保存在浏览器本地 - 前端项目请勿直接用于高敏感生产环境 > 如果用于正式生产环境，建议通过你自己的后端进行中转，而不是让浏览器直接持有真实密钥。 --- ### 12.3 模型名称 实际请求时传给接口的模型标识。 示例： ```text README.md gpt-4o-mini gpt-4.1 deepseek-chat deepseek-reasoner qwen-plus moonshot-v1-8k ``` 说明： - 这里填的是接口真实使用的模型名称 - 配置列表里显示的“配置别名”可以和模型名称不同 --- ### 12.4 温度 Temperature 控制回答的随机性和发散程度。 通俗理解： - **越低**：越稳定、越保守、越一致 - **越高**：越灵活、越发散、越有创造性 建议值： - **0 ~ 0.3**：代码、SQL、翻译、提取信息 - **0.4 ~ 0.7**：通用问答 - **0.8 ~ 1.2**：创意写作、头脑风暴 常用推荐： ```text README.md 代码场景：0.2 日常问答：0.7 创意写作：1.0 ``` > 建议界面文案可理解为“生成温度”或“回答随机性”。 --- ### 12.5 最大生成长度 max_tokens 控制模型最多生成多少 token。 你可以理解为： - 值越大，允许生成的回复越长 - 值越小，回复可能提前结束 注意： - 不同模型支持的最大值不同 - 填得过大不一定生效，取决于模型服务商限制 - 设置过大可能增加响应成本和耗时 建议： - 普通聊天：`1024 ~ 4096` - 长回答：`4096 ~ 8192` - 具体以模型平台支持为准 --- ### 12.6 上下文关联轮数 控制本次提问会带上多少历史消息一起发给模型。 说明： - 值越大，AI 越“记得之前说过什么” - 值越小，请求越轻，速度可能更快 例如： - 设为 `0`：只发送当前问题 - 设为 `3`：会带上最近 3 轮上下文（通常对应若干条历史消息） 建议： - 普通问答：`3 ~ 10` - 长对话、复杂上下文：适当调高 --- ### 12.7 流式输出 是否边生成边显示。 开启后： - AI 会一边返回一边展示 - 体验更像真实聊天 关闭后： - 要等服务端全部生成完才一次性显示 建议： - 日常使用建议开启 --- ### 12.8 系统提示词 System Prompt 用于给模型设定身份、风格、规则。 示例： ```text README.md 你是一个专业的前端开发顾问，请使用中文回答，回答尽量清晰简洁。 ``` 再比如： ```text README.md 你是一个 SQL 优化专家。请优先分析索引、执行计划、查询条件，并给出优化后的 SQL。 ``` 用途： - 设定 AI 人设 - 约束输出风格 - 统一回答格式 - 强化某一类任务能力 --- ## 13. 配置管理说明 ### 11.1 配置别名 配置别名是给人看的名字，例如： - DeepSeek 生产环境 - GPT-4o 测试 - 本地代码模型 它用于： - 配置列表展示 - 快速切换时区分不同配置 ### 11.2 保存当前配置 将当前填写的参数保存到本地配置列表中。 ### 11.3 另存为 保留当前配置，同时创建一条新的配置记录。 适合场景： - 在现有模型基础上微调参数 - 针对不同任务保存不同方案 ### 11.4 重命名 / 删除 / 选择 在配置管理区可直接： - 修改名称 - 删除配置 - 选择某配置立即生效 ### 11.5 自动保存 配置字段修改后会自动保存到浏览器本地。 说明： - 刷新页面后不会丢失 - 更换浏览器或清理本地缓存后会失效 --- ## 14. 模型参数推荐方案 如果你不确定怎么配，可以直接参考下面几套常见方案。 ### 14.1 代码开发 / SQL 生成 - 温度：`0.1 ~ 0.3` - max_tokens：`2048 ~ 8192` - 上下文轮数：`3 ~ 8` - 流式输出：建议开启 - System Prompt：强调严谨、结构清晰、优先给可执行结果 ### 14.2 日常问答 / 办公助手 - 温度：`0.5 ~ 0.7` - max_tokens：`1024 ~ 4096` - 上下文轮数：`3 ~ 10` - 流式输出：建议开启 - System Prompt：强调简洁、准确、中文回答 ### 14.3 创意写作 / 头脑风暴 - 温度：`0.8 ~ 1.1` - max_tokens：`2048 ~ 8192` - 上下文轮数：`2 ~ 6` - 流式输出：可开启 - System Prompt：强调创意、多角度发散、风格化表达 ### 14.4 长对话 / 持续上下文任务 - 温度：`0.4 ~ 0.7` - max_tokens：按模型上限合理设置 - 上下文轮数：`8 ~ 20` - 流式输出：建议开启 - 注意：上下文越长，请求越重，成本也更高 --- ## 15. 支持的模型接入方式 只要你的服务端接口兼容 OpenAI Chat Completions 风格，一般都可以接入。 常见包括： - OpenAI - DeepSeek - 通义千问兼容网关 - Moonshot - OpenRouter - One API / New API 类聚合网关 - 本地中转服务 - 企业内部封装接口 如果你的平台接口协议略有差异，可以修改： ```text README.md src/services/chat.ts ``` 中的请求逻辑进行适配。 --- ## 16. 二次开发建议 你可以基于本项目继续扩展： - 多会话管理 - 会话标题自动生成 - 联网搜索 - 文件上传 - 知识库问答 - Prompt 模板市场 - 用户登录与权限控制 - 服务端代理转发 - Token 消耗统计 - 模型响应耗时统计 推荐重点关注目录： - `src/components`：UI 层 - `src/stores`：状态管理 - `src/services/chat.ts`：模型请求逻辑 - `src/utils/markdown.ts`：Markdown 与代码渲染逻辑 --- ## 17. 环境变量与多环境配置建议 当前项目主要通过界面配置模型参数，不强依赖 `.env`。 但如果你在开发或部署时需要区分不同环境，建议自行补充 Vite 环境变量，例如： ```env README.md VITE_APP_TITLE=ChatAI VITE_DEFAULT_BASE_URL=https://your-proxy-domain.com/api VITE_DEFAULT_MODEL=deepseek-chat ``` 在代码中可通过： ```ts README.md import.meta.env.VITE_DEFAULT_BASE_URL ``` 读取。 ### 17.1 推荐用途 环境变量适合放： - 默认站点标题 - 默认代理地址 - 默认模型名称 - 是否开启调试模式 ### 17.2 不建议放的内容 不建议把真实生产 API Key 放到前端 `.env` 中，因为最终仍会被打包进前端资源里。 --- ## 18. 安全说明 本项目当前是前端直连模型接口的方式，因此需要注意： 1. **API Key 会出现在浏览器端** 2. 不适合直接用于高安全生产环境 3. 若需企业正式使用，建议接入后端代理层 推荐做法： - 前端 -> 你自己的后端 -> 模型服务商 这样可以： - 隐藏真实 API Key - 增加权限控制 - 做日志审计 - 限流与计费统计 --- ## 19. 常见问题 ### 15.1 为什么提示 BaseURL 不合法？ 请确认： - 以 `http://` 或 `https://` 开头 - 没有多余空格 - 地址格式正确 ### 15.2 为什么填了 Key 还是请求失败？ 可能原因： - BaseURL 填错 - 模型名称填错 - API Key 无效 - 服务端不支持当前模型 - 跨域限制 - 服务商接口格式与当前实现不完全兼容 ### 15.3 为什么模型没有记住上文？ 请检查： - 上下文关联轮数是否设置过小 - 当前会话是否被清空 - 是否切换了配置或会话 ### 19.4 为什么代码没有按代码块显示？ 项目已支持 Markdown 和部分自动识别，但最稳定的方式仍然是模型明确输出 fenced code block： ```text README.md ```sql select * from users; ``` ``` ### 19.5 为什么前端配置了也调用不通？ 还需要额外检查： - 模型平台是否允许浏览器跨域访问 - 是否被公司内网 / 网关限制 - 是否需要通过代理路径访问 - 模型平台是否要求完整路径，例如 `/v1` 例如有的平台 BaseURL 需要写成： ```text README.md https://api.xxx.com/v1 ``` 而不是只写域名。 ### 19.6 为什么刷新后配置还在？ 因为配置默认保存在浏览器本地存储中，这是当前项目的设计行为。 如果你想改成： - 只保存在当前会话 - 保存到服务端 - 按用户账号同步 则需要自行扩展存储逻辑。 --- ## 20. 开发脚本一览 ```bash README.md npm run dev # 启动开发环境 npm run build # 生产打包 npm run preview # 预览打包结果 npm run type-check # TypeScript 类型检查 ``` --- ## 21. 参与贡献 欢迎继续完善本项目，例如： - 优化 UI 细节 - 增强代码块展示 - 增加更多模型适配 - 提升移动端体验 - 增加文件上传/知识库等能力 贡献流程： 1. Fork 本仓库 2. 新建分支 3. 提交修改 4. 发起 Pull Request --- ## 22. 许可证 如仓库未单独声明 License，请根据你的实际需求补充许可证文件。 常见可选： - MIT - Apache-2.0 - GPL-3.0 --- ## 23. 补充说明 如果你准备把这个项目用于正式生产，建议优先补齐以下能力： - 后端代理层 - 用户体系 - 配置加密存储 - 请求日志 - 错误监控 - Token / 费用统计 - 多环境部署配置 这样会更适合团队长期使用。