本篇文章记录 HuiVision 慧视项目的后端开发进展，重点介绍 FastAPI 后端如何对接视觉大模型、阿里云语音服务和高德地图服务，以及小程序端如何调用这些接口完成图片识别、语音播报和出行引导。

## 一、后端在项目中的作用

HuiVision 是一个微信小程序项目，但我没有把所有逻辑都放在小程序端。主要原因是项目需要调用多个第三方服务，如果直接在小程序端请求，会有几个问题：

1. API 密钥容易暴露。
2. 第三方接口格式不统一，小程序代码会变复杂。
3. 后续切换模型或服务商时维护成本高。

因此，我使用 FastAPI 搭建了一个后端中转层。小程序只需要调用我自己定义的接口，真正的密钥和第三方服务调用都放在后端。

## 二、后端接口模块划分

后端目前主要分为三个模块：

```text
backend/app/api/
├── navigation.py    # 高德地图导航相关接口
├── speech.py        # 语音识别和语音合成接口
└── travel.py        # 出行模式 AI 分析和指令解析
```

另外，`backend/app/main.py` 负责创建 FastAPI 应用、注册路由和挂载静态资源目录。

## 三、会视模式图片分析接口

会视模式对应接口为：

```text
POST /v1/vision/analyze
```

小程序端通过 `wx.uploadFile` 上传图片，后端读取图片内容后转成 Base64，然后把它发送给视觉大模型。

接口的主要流程是：

1. 接收图片文件。
2. 判断图片是否为空。
3. 根据文件后缀推断 MIME 类型。
4. 将图片编码成 Base64。
5. 请求视觉大模型接口。
6. 流式返回分析结果。

这个接口主要用于“会视模式”的快速识别，例如识别眼前物体、障碍物或场景。

## 四、出行模式场景分析接口

出行模式对应接口为：

```text
POST /api/travel/analyze
```

相比会视模式，出行模式不仅需要图片，还需要结合上下文信息，例如：

- 当前经纬度。
- 是否正在导航。
- 当前导航指令。
- 距离下一个转向点的距离。
- 预警距离和灵敏度设置。

后端会把这些信息组合进 prompt 中，让视觉模型输出结构化 JSON，例如：

```json
{
  "summary": "前方有人行道",
  "sceneType": "sidewalk",
  "obstacleLevel": "normal",
  "obstacles": [],
  "instruction": "沿右侧缓慢直行"
}
```

这样小程序端就可以根据 `obstacleLevel` 判断是否震动提醒，也可以把 `instruction` 交给 TTS 播放。

## 五、语音识别与语音合成

项目中语音能力非常重要，因为目标用户是视障人士，单纯依靠屏幕文字并不合适。

目前后端实现了两个接口：

```text
POST /api/speech/stt
POST /api/speech/tts
```

### 1. STT 语音转文字

小程序录音后上传音频文件，后端调用阿里云语音识别接口，将语音转换为文本。

这个功能主要用于语音指令，例如：

- “导航到图书馆”
- “开始实时引导”
- “停止导航”
- “快速分析”

### 2. TTS 文字转语音

后端把 AI 分析结果或导航提示转换成语音文件，然后保存到 `backend/static/` 目录下，并返回音频访问地址。

小程序拿到地址后，通过 `wx.createInnerAudioContext()` 播放。

在联调中我遇到过一个问题：后端返回的是 `/static/xxx.mp3` 这种相对路径，小程序直接播放会失败。后来我在小程序端把它拼接成完整地址：

```js
this.audioPlayer.src = audioUrl.indexOf("http") === 0 ? audioUrl : API_URL + audioUrl;
```

这样真机调试时就能正确播放后端生成的音频。

## 六、导航相关接口

出行模式还接入了高德地图，主要有两个接口：

```text
POST /api/navigation/route
POST /api/navigation/instruction
```

### 1. 路线规划

用户输入目的地后，后端先调用高德地理编码接口，把地点名称转换为经纬度，然后调用步行路径规划接口。

后端会生成一个本地 `routeId`，并把路径步骤暂存在内存中，方便后续查询。

### 2. 获取当前导航指令

小程序持续上传当前位置后，后端会根据当前位置和路线步骤计算当前最接近的导航步骤，并返回：

```json
{
  "instruction": "向前步行100米后左转",
  "distanceToTurn": 35.2
}
```

这个结果可以和视觉分析结果融合，形成更适合出行场景的提示。

## 七、前后端联调方式

小程序端主要通过 `envList.js` 中的 `API_URL` 指向后端地址。

本地开发时，如果只在微信开发者工具里调试，可以使用：

```js
const API_URL = "http://127.0.0.1:8000";
```

如果用手机真机调试，需要改成电脑的局域网 IP，例如：

```js
const API_URL = "http://192.168.1.10:8000";
```

后端启动命令：

```bash
PYTHONPATH=backend uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

接口文档地址：

```text
http://127.0.0.1:8000/docs
```

## 八、目前完成的进展

这一阶段我完成了：

1. FastAPI 后端基础结构搭建。
2. 图片上传与视觉分析接口。
3. 出行模式图片和上下文融合分析。
4. 阿里云语音识别和语音合成接口。
5. 高德地图路线规划和导航指令接口。
6. 小程序端图片上传、录音上传、音频播放等基础联调。
7. 后端路由统一加 `/api` 前缀，使接口结构更规范。

## 九、遇到的问题与解决

### 问题 1：接口路径不统一

一开始后端接口是 `/travel/analyze`，而小程序端写的是 `/api/travel/analyze`。这会导致请求 404。

解决方法是在 FastAPI 注册路由时统一添加 `/api` 前缀：

```python
app.include_router(travel_router, prefix="/api")
```

### 问题 2：音频相对路径无法播放

后端返回 `/static/xxx.mp3`，小程序需要完整 URL。

解决方法是在小程序端拼接 `API_URL`。

### 问题 3：第三方服务密钥管理混乱

最开始部分密钥写在代码里，后续整理时统一改成环境变量读取，避免泄露。

## 十、小结

本阶段的重点是让项目从“页面原型”变成真正能调用后端能力的应用。通过 FastAPI，我把视觉模型、语音服务和地图服务统一封装起来，小程序端只负责交互和展示。

下一阶段我会继续记录项目结构规范化、密钥安全处理和 GitHub 上传过程。