Appearance

使用问题 ​

本文档汇总了 CueMate 功能使用过程中的常见问题和解决方案。

提示

如果你遇到的问题在这里找不到答案，可以查看 功能手册 获取更详细的功能说明。

1. macOS 平台 ​

1.1 语音识别不准确 ​

问题描述：使用语音识别功能时，识别的文字与实际说话内容不符，或者有较多错误。

提升识别准确率的关键因素

环境 > 设备 > 发音 > 配置

最重要的是保证安静的环境和清晰的发音，其次才是设备和参数调整。

优化建议：

  1. 环境优化：

    • 选择安静的环境，避免背景噪音
    • 关闭电风扇、空调等可能产生噪音的设备
    • 避免在嘈杂的公共场所使用

  2. 设备调整：

    • 调整麦克风位置，距离嘴巴 15-20cm 最佳
    • 使用外置麦克风，音质通常优于内置麦克风
    • 确保麦克风未被遮挡或覆盖

  3. 发音技巧：

    • 清晰发音，避免含糊不清
    • 语速适中，不要过快或过慢
    • 避免使用方言，尽量使用标准普通话

  4. 系统设置：

1.2 语音识别延迟高 ​

问题描述：说话后需要等待较长时间才能看到识别结果，影响使用体验。

解决方案：

  1. 设备优化：

    • 使用有线麦克风代替蓝牙麦克风（蓝牙有延迟）
    • 确保麦克风连接稳定，避免松动

  2. 系统资源：

    • 关闭不必要的后台程序，释放 CPU 和内存
    • 打开 Docker Desktop 设置，增加分配给 Docker 的资源
    • 建议：内存 4GB+，CPU 2 核+

  3. 网络检查：

    • 检查网络连接是否稳定
    • 确认 cuemate-asr 服务正常运行（端口 10095）
    • 查看 容器监控 确认服务状态

  4. 服务重启：

    • 在容器监控页面重启 cuemate-asr 服务
    • 完全退出并重新启动 CueMate 应用

1.3 无法捕获系统音频 ​

问题描述：使用扬声器测试或面试训练时，无法识别扬声器播放的音频内容。

需要系统权限

捕获系统音频需要 macOS"录屏与系统录音"权限。请按照以下步骤检查并授予权限。

macOS 解决方案：

  1. 检查权限：

    • 打开 系统设置 > 隐私与安全性 > 录屏与系统录音
    • 确认 CueMate 已被勾选
    • 如果未勾选，请勾选并重启 CueMate

  2. 权限说明：

备选方案：使用虚拟音频设备（高级用户）

适用场景：不想授予录屏权限，或系统音频捕获不稳定时

操作步骤：

  1. 安装 BlackHole 等虚拟音频设备
  2. 将扬声器输出路由到虚拟设备
  3. 在语音设置中选择虚拟设备作为输入

推荐工具：BlackHole - 开源免费的 macOS 虚拟音频驱动

1.4 API Key 无效 ​

问题描述：在模型设置中添加 API Key 后，测试连接提示"API Key 无效"或"认证失败"。

常见 API Key 格式

不同平台的 API Key 格式不同，请注意区分：

平台格式示例长度
OpenAIsk-proj-xxxxx...51 位
Azure OpenAIa1b2c3d4e5f6...32 位
智谱 AIxxxxxx.xxxxxx包含 .
Moonshot (Kimi)sk-xxxxx...56 位
通义千问sk-xxxxx...不定长

检查步骤：

  1. 格式检查：

    • 确认 API Key 格式正确，没有多余的空格
    • 复制时避免选中换行符
    • 使用纯文本编辑器查看是否有隐藏字符

  2. 有效性检查：

    • 确认 API Key 未过期
    • 登录对应平台检查 API Key 状态
    • 如已过期，重新生成新的 API Key

  3. 账户检查：

    • 确认账户余额充足
    • 某些平台需要充值后才能使用 API
    • 检查是否有使用限额或速率限制

  4. 服务可用性：

    • 检查对应 AI 服务是否正常运行
    • 访问官网确认服务状态
    • 尝试更换其他 API Key 测试

详见 模型设置。

1.5 测试连接失败 ​

问题描述：在模型设置页面点击"测试连接"后，提示连接失败或超时。

排查步骤：

  1. 检查网络连接：

    • 确认网络连接正常
    • 尝试访问对应 AI 服务的官网
    • 检查是否需要科学上网（如 OpenAI）

  2. 验证 API URL 正确：

    • 检查 API Endpoint 地址是否正确
    • OpenAI: https://api.openai.com/v1
    • Azure OpenAI: 需要填写完整的资源地址
    • 其他平台请参考官方文档

  3. 确认 API Key 有效：

    • 参考问题 4 检查 API Key
    • 尝试在官方 API 工具中测试
    • 确认权限范围包含所需的模型

  4. 查看错误日志：

    • 打开 日志管理 页面
    • 查看 llm-router 服务的错误日志
    • 根据具体错误信息进行排查

1.6 模型响应慢 ​

问题描述：向 AI 提问后，等待很长时间才收到回答，或者回答速度很慢。

模型速度对比（快 → 慢）

最快：GPT-3.5-turbo、DeepSeek、Kimi 较快：GPT-4o-mini、智谱 GLM-4-Flash 较慢：GPT-4、Claude-3-Opus、GPT-4o

日常使用推荐选择"最快"或"较快"级别的模型。

优化方法：

  1. 调整模型参数：

    • 降低 max_tokens 参数（默认 2000）
    • 减少 temperature 值以加快生成速度
    • 在 模型设置 中调整

  2. 更换模型：

    场景推荐模型理由
    日常对话GPT-3.5-turbo速度快，成本低
    代码生成DeepSeek Coder专业且快速
    文档分析Kimi (Moonshot)长文本能力强
    复杂推理GPT-4准确度高

  3. 启用缓存（如果支持）：

    • 某些模型支持缓存机制
    • 相同问题会直接返回缓存结果
    • 查看模型文档确认是否支持

  4. 检查网络速度：

    • 使用网络测速工具检查带宽
    • 尝试切换网络连接（Wi-Fi → 有线）
    • 科学上网时选择更快的节点

1.7 文档上传失败 ​

问题描述：在知识库中上传文档时，提示上传失败或处理失败。

IMPORTANT

支持的文档格式和限制：

  • 支持格式：.txt, .md, .pdf, .docx, .doc
  • 单文件大小：最大 100MB
  • 不支持：图片、视频、压缩包等多媒体文件

可能原因：

  1. 文件格式不支持：

    • 支持格式：.txt, .md, .pdf, .docx, .doc
    • 不支持图片、视频等多媒体文件
    • 压缩文件需要先解压

  2. 文件大小超限：

    • 单个文件最大 100MB
    • 建议将大文件拆分成多个小文件
    • 或删除文档中的多余内容

  3. 磁盘空间不足：

    • 检查系统磁盘剩余空间
    • 确保至少有 1GB 可用空间
    • 清理不必要的文件

  4. 文档内容损坏：

    • 尝试重新生成文档
    • 使用其他工具打开文档检查完整性
    • 转换为其他格式后再上传

解决方案：

  • 转换文件格式为支持的格式
  • 压缩或拆分文件大小
  • 清理磁盘空间后重试
  • 检查文档完整性，确保文件未损坏

详见 向量知识库。

1.8 知识库检索无结果 ​

问题描述：向 AI 提问时，知识库中明明有相关内容，但检索不到结果。

TIP

知识库检索效果与文档数量和质量密切相关。建议：

  • 上传 10+ 个相关领域文档
  • 文档内容要详细且结构化
  • 使用精确的专业术语提问

优化建议：

  1. 上传更多相关文档：

    • 确保知识库中包含相关领域的文档
    • 文档内容要覆盖提问的知识点
    • 建议上传 10+ 个相关文档以提高召回率

  2. 优化查询关键词：

    • 使用更精确的关键词
    • 避免使用过于宽泛的词语
    • 尝试使用同义词或相关术语

  3. 调整检索参数：

    • 在知识库设置中调整 Top-K 参数（默认 5）
    • 增加 Top-K 可以检索更多相关文档
    • 但也会增加噪音，建议逐步调整

  4. 重新索引文档：

    • 在知识库管理页面重新索引所有文档
    • 删除后重新上传文档
    • 确认向量化过程正常完成

1.9 向量化失败 ​

问题描述：上传文档后，显示"向量化失败"或"处理失败"。

检查项：

  1. 文档可读性：

    • 确认文档可以正常打开
    • 检查文档编码是否正确（建议 UTF-8）
    • 确保文档内容不是纯图片或扫描件

  2. 嵌入服务检查：

    • 查看 容器监控
    • 确认 cuemate-rag-service 服务正常运行
    • 检查 cuemate-chroma 向量数据库状态

  3. 系统资源：

    • 向量化需要一定的 CPU 和内存
    • 确保系统资源充足
    • 暂停其他高负载任务

  4. 查看错误日志：

    • 打开 日志管理
    • 查看 rag-service 的错误日志
    • 根据具体错误信息排查

1.10 AI 回答质量差 ​

问题描述：在模拟面试或提问时，AI 的回答质量不高，内容不准确或不相关。

改进方法：

  1. 使用更好的模型：

    • 优先选择 GPT-4、Claude-3.5-Sonnet 等高质量模型
    • 避免使用过时或质量较差的模型
    • 在 模型设置 中配置

  2. 优化提示词：

    • 在 提示词管理 中调整系统提示词
    • 提供更详细的上下文信息
    • 明确回答的格式和要求

  3. 完善知识库：

    • 上传更多相关领域的文档到 向量知识库
    • 确保文档内容准确、权威
    • 定期更新知识库内容

  4. 调整模型参数：

    • 降低 temperature（0.3-0.7）使回答更确定
    • 增加 max_tokens 允许更详细的回答
    • 调整 top_p 控制回答的多样性

1.11 面试题目不匹配职位 ​

问题描述：在模拟面试中，AI 生成的面试题目与申请的职位关联性不强。

解决方案：

  1. 完善职位信息：

    • 在 新建岗位 中填写详细的 JD
    • 包含岗位职责、技能要求、工作内容
    • 信息越详细，生成的题目越精准

  2. 更新技能要求：

    • 明确列出需要的技术栈
    • 标注重点考察的能力
    • 补充特殊要求或加分项

  3. 手动选择题目：

    • 在 面试押题 中添加相关题目
    • 标记题目类型和难度
    • 面试时会优先使用押题库中的题目

  4. 添加自定义题目：

    • 根据实际面试经验添加题目
    • 包含答案和评分标准
    • 持续完善题库

1.12 面试评分不准确 ​

问题描述：在模拟面试中，AI 对回答的评分与预期不符，或者评价不够客观。

可能原因：

  1. 回答不完整：

    • 回答过于简短，缺少关键信息
    • 未涵盖问题的所有要点
    • 缺少具体案例或数据支撑

  2. 模型理解偏差：

    • 使用的模型对专业术语理解有限
    • 某些领域的知识不够深入
    • 评估标准与人类面试官存在差异

  3. 评分标准不合理：

    • 默认评分标准可能不适用所有场景
    • 不同职位的评分侧重点不同
    • 需要针对性调整

优化建议：

  1. 完整回答所有要点：

    • 使用 STAR 法则（情境-任务-行动-结果）
    • 包含技术细节和数据支撑
    • 结构化表达，层次清晰

  2. 调整评分提示词：

    • 在 提示词管理 中修改面试评估提示词
    • 明确评分维度和权重
    • 提供评分示例

  3. 参考标准答案：

    • 在面试押题中添加标准答案
    • 对比自己的回答与标准答案的差异
    • 不断优化回答方式

1.13 数据丢失 ​

问题描述：面试记录、对话历史、知识库文档等数据突然丢失。

预防措施：

  1. 定期备份数据：

    • 在系统设置中启用自动备份
    • 手动导出重要数据
    • 建议每周备份一次

  2. 启用自动备份：

    • 配置备份频率和保留策略
    • 设置备份存储位置
    • 验证备份文件完整性

  3. 使用云端存储：

    • 将备份文件同步到云端（iCloud、OneDrive 等）
    • 启用版本控制
    • 定期检查同步状态

恢复方法：

  1. 从备份恢复：

    • 在系统设置中选择备份文件
    • 执行数据恢复操作
    • 验证恢复后的数据完整性

  2. 查看回收站：

    • 某些删除操作会先移到回收站
    • 检查是否可以恢复
    • 尽快恢复，避免被彻底删除

  3. 联系技术支持：

    • 如果以上方法都无效
    • 提供详细的问题描述和日志
    • 联系方式见文档底部

1.14 导入导出失败 ​

问题描述：尝试导入或导出数据时，提示失败或生成的文件无法使用。

检查项：

  1. 文件格式检查：

    • 导入时确认文件格式正确
    • 支持的格式：JSON、CSV（根据功能不同）
    • 文件未损坏或被修改

  2. 文件完整性：

    • 检查文件大小是否正常
    • 使用文本编辑器查看文件内容
    • 确认 JSON 格式正确，无语法错误

  3. 权限检查：

    • 打开 系统设置 > 隐私与安全性 > 文件和文件夹
    • 确认 CueMate 有访问对应文件夹的权限
    • 如果没有，点击"+"添加权限

  4. 磁盘空间：

    • 导出时确保磁盘空间充足
    • 建议至少 1GB 可用空间
    • 清理临时文件

1.15 麦克风/扬声器无法识别 ​

问题描述：在语音设置或语音测试页面，看不到麦克风或扬声器设备。

解决方案：

  1. 检查设备连接：

    • 确认设备已正确连接到电脑
    • 尝试重新插拔设备
    • 检查设备是否正常工作（在其他应用中测试）

  2. 检查系统设置：

    • 打开 系统设置 > 声音
    • 切换到 输入 标签查看麦克风
    • 切换到 输出 标签查看扬声器
    • 确认设备在列表中并设为默认设备

  3. 刷新设备列表：

    • 点击设备选择框的刷新按钮
    • 或重启 CueMate 应用
    • 设备会自动重新扫描

  4. 检查权限：

    • 打开 系统设置 > 隐私与安全性 > 麦克风
    • 确认 CueMate 已被勾选

详见 语音设置。

1.16 服务启动失败 ​

问题描述：在容器监控页面看到某些服务状态为"已停止"或"错误"。

解决方案：

  1. 查看服务状态：

    • 打开 容器监控
    • 检查所有 6 个服务的状态
    • 记录异常服务的名称

  2. 查看错误日志：

    • 点击异常服务的"日志"按钮
    • 查看最近的错误信息
    • 截图保存用于排查

  3. 重启服务：

    • 点击异常服务的"重启"按钮
    • 等待服务重启完成（约 30 秒）
    • 刷新页面查看状态

  4. 检查依赖服务：

    • 某些服务依赖其他服务
    • 确保 Docker Desktop 正常运行
    • 检查端口是否被占用

详见 容器监控 - 常见问题。

1.17 控制栏无法操作 ​

问题描述：点击悬浮控制栏上的按钮没有反应，或者控制栏无法拖动。

解决方案：

  1. 检查交互模式：

    • 点击控制栏上的"交互模式"按钮
    • 确认处于"交互"模式（图标高亮）
    • "穿透"模式下控制栏无法点击

  2. 重启应用：

    • 完全退出 CueMate（菜单栏 > 退出）
    • 重新启动应用
    • 检查控制栏是否恢复正常

  3. 检查服务状态：

    • 某些按钮依赖后端服务
    • 打开 容器监控
    • 确认所有服务正常运行

  4. 重置窗口位置：

    • 在系统设置中重置窗口位置
    • 控制栏会回到默认位置
    • 重新拖动到合适位置

1.18 许可证激活失败 ​

问题描述：输入许可证密钥后，提示激活失败或密钥无效。

解决方案：

  1. 检查密钥格式：

    • 确认密钥格式正确，无多余空格
    • 复制粘贴时避免遗漏字符
    • 检查是否包含特殊字符

  2. 检查有效期：

    • 确认许可证未过期
    • 登录许可证管理后台查看状态
    • 如已过期，需要续费

  3. 检查激活次数：

    • 许可证可能有设备数量限制
    • 在许可证管理后台解绑旧设备
    • 重新激活当前设备

  4. 网络连接：

    • 激活需要连接许可证服务器
    • 检查网络连接是否正常
    • 稍后重试或联系技术支持

详见 许可证管理。

1.19 日志文件过大 ​

问题描述：日志文件占用大量磁盘空间，导致磁盘空间不足。

解决方案：

  1. 清理旧日志：

    • 打开 日志管理
    • 选择日期范围
    • 批量删除旧日志文件

  2. 调整日志级别：

    • 在系统设置中降低日志级别
    • 生产环境建议使用 WARN 或 ERROR 级别
    • 避免长期使用 DEBUG 级别

  3. 启用日志轮转：

    • 配置日志自动轮转策略
    • 设置单个日志文件大小限制
    • 设置日志保留天数（如 7 天）

  4. 定期清理：

    • 建议每周清理一次日志
    • 或配置自动清理任务
    • 保留最近 3-7 天的日志即可

1.20 应用更新失败 ​

问题描述：检测到新版本后，更新下载失败或安装失败。

解决方案：

  1. 检查网络连接：

    • 确认网络连接稳定
    • 下载大文件（约 5GB）需要稳定网络
    • 避免使用不稳定的 Wi-Fi

  2. 检查磁盘空间：

    • 确保至少有 10GB 可用空间
    • 更新需要下载新版本并解压
    • 清理磁盘后重试

  3. 手动下载更新：

    • 访问官网下载最新版本
    • 或从百度网盘/GitHub 下载
    • 手动安装更新包

  4. 查看更新日志：

    • 打开 日志管理
    • 查看更新过程中的错误信息
    • 根据错误信息排查

详见 版本升级。

2. Windows 平台 ​

开发中

Windows 版本正在开发中，敬请期待。

如果你对 Windows 版本有任何建议或需求，欢迎通过以下方式反馈：

获取更多帮助 ​

如果以上方法都无法解决你的问题，可以通过以下方式获取帮助：

查看文档 ​

联系技术支持 ​

提交问题时，请提供：

  1. CueMate 版本号
  2. 操作系统版本
  3. 详细的问题描述和截图
  4. 相关的错误日志
  5. 已尝试的解决方法

Released under the GPL-3.0 License.

Copyright © 2025-present CueMate Team