Nora 智能问答功能部署文档

功能介绍

Nora 是智能问答助手，能够理解自然语言问题并转换为精确的业务查询。

核心能力：

将模糊的业务问题转换为准确的系统查询
支持多轮对话，理解上下文
基于知识库的智能术语匹配
实时流式响应

技术架构：

用户提问 → Nora Agent → 知识库检索 → 大语言模型 → 返回精确问题 → Alisa理科生模型进行语义理解

系统要求

外部 API 要求

Nora 需要以下两个 API 服务：

大语言模型 API (必需)
- 接口规范：兼容 OpenAI /chat/completions 接口格式
- 模型要求：非推理类模型，需支持工具调用 (Function Calling / Tool Use)
- 返回格式：需与 OpenAI 返回风格一致
- 可选服务商：
  - DeepSeek：https://platform.deepseek.com/
  - 阿里通义千问：https://dashscope.aliyuncs.com/
  - 智谱 AI：https://open.bigmodel.cn/
  - 其他 OpenAI 兼容接口
Embedding API (必需)
- 接口规范：兼容 OpenAI /embeddings 接口格式
- 用途：文本向量化，用于知识库检索
- 可选服务商：
  - 智谱 AI：https://open.bigmodel.cn/
  - OpenAI：https://platform.openai.com/
  - 本地部署 BGE-M3（通过 Ollama）
  - 其他 OpenAI 兼容的 Embedding 服务

依赖服务

系统需要以下数据库服务（通过 Docker 自动部署）：

PostgreSQL 15+ (含 pgvector 扩展)

外部 API

需要申请以下 API Key：

向量化模型api (必需)
- 用途：文本向量化
- 选项：zhipu，BGE等
大语言模型 (必需，以下任选其一)
- DeepSeek：https://platform.deepseek.com/
- 阿里通义千问：https://dashscope.aliyuncs.com/
- OpenAI 兼容接口

注：

Nora在DeepSeek、Qwen的官方API上经过深度测试，如果是独立部署的以上开源模型，需保证通信格式和参数与官方API一致。
大语言模型必须是支持工具调用的对话模型。
不推荐用带思考模式的模型。
以上模型均推荐使用最新版本，如DeepSeek V3.2、qwen3-max。

快速部署

1. 下载配置文件

确认项目根目录包含 docker-compose.yml 文件。

2. 配置环境变量

编辑 docker-compose.yml，修改以下配置：

services:
  app:
    environment:
      # 向量化模型配置（zhipu或其他）
      - ZHIPUAI_API_KEY=可选，替换为你的智谱AI_Key
      # 如果使用自定义向量化模型，需要配置以下参数
      - EMBEDDING_PROVIDER=custom
      - EMBEDDING_URL=自定义向量化模型的URL，如：https://api.deepseek.cn/v1/embeddings
      - EMBEDDING_API_KEY=自定义向量化模型的API Key，如：sk-xxx...
      - EMBEDDING_MODEL=自定义向量化模型的模型名称，如：deepseek-embedding

      # 数据库配置（默认值通常无需修改）
      - PG_HOST=postgres
      - PG_USER=postgres
      - PG_PASSWORD=postgres

      # 多语言支持（可选，默认关闭）
      # 注意：开启后会增加向量化时间和学习阶段 token 消耗
      # - ENABLE_EN_TRANSLATION=true    # 英文翻译支持
      # - ENABLE_TRADITIONAL_CN=true    # 繁体中文支持

  postgres:
    container_name: postgres
    restart: always
    image: docker.1ms.run/pgvector/pgvector:pg15-trixie
    privileged: true
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: mydatabase
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata: {}

重要配置项说明：

配置项	说明	示例
`ENABLE_EN_TRANSLATION`	英文翻译支持开关，默认关闭。开启后会增加向量化时间和学习阶段 token 消耗	`true` / `false` (默认)
`ENABLE_TRADITIONAL_CN`	繁体中文支持开关，默认关闭。开启后会增加向量化时间和学习阶段 token 消耗	`true` / `false` (默认)

在 "系统参数 - 配置大语言模型" 中添加用于nora的模型，并启用。

3. 启动服务

在项目根目录执行：

# 启动所有服务
docker-compose up -d

# 查看启动日志
docker-compose logs -f yiask -n 100

4. 等待初始化

首次启动需要 1-2 分钟进行初始化，日志中看到以下信息表示成功：

✅ Created database: alisa_chatbi
使用LLM配置: deepseek-chat
yiask listening on port 3052

5. 访问系统

打开浏览器访问：http://服务器IP:3052
配置 Nora 大语言模型：
- 进入 "系统设置" -> "大语言模型配置"
- 配置用于 Nora 的大模型 API 链接
- 打开 "Nora" 选项卡
- 点击保存
点击 "业务建模-重新学习所有表"，等待系统完成学习。
- 可通过后台日志查看向量库的学习进度和结果：
```
docker-compose logs -f yiask -n 100
```
开始使用 Nora 智能问答功能。

配置说明

基础环境变量

按前文要求的配置环境变量。

功能验证

1. 检查服务状态

# 查看所有服务运行状态
docker-compose ps

# 预期输出（所有服务 State 为 Up）
NAME                IMAGE                              STATE
yiask               docker.1ms.run/chatbi/mini:latest  Up
postgres            pgvector/pgvector:pg15-trixie      Up

2. 检查应用日志

docker-compose logs app | tail -20

确认看到以下关键日志：

✅ Created database: alisa_xxx - 数据库初始化成功
使用LLM配置: deepseek-chat - LLM 配置加载成功
yiask listening on port 3052 - 服务启动成功

3. 检查 PostgreSQL 向量扩展

docker-compose exec postgres psql -U postgres -d alisa_chatbi -c "SELECT extname FROM pg_extension WHERE extname='vector';"

预期输出：

 extname
---------
 vector

4. 测试 Nora 功能

方法一：通过界面测试

访问 http://服务器IP:3052
登录后在对话界面输入问题，例如："本月销售额是多少"
观察 Nora 的响应

方法二：通过 API 测试

# 1. 获取登录 Token
TOKEN=$(curl -s -X POST http://localhost:3052/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your_password"}' \
  | grep -o '"token":"[^"]*' | cut -d'"' -f4)

# 2. 测试 Nora 对话
curl -X POST http://localhost:3052/api/v1/nora/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "question": "今年销售额",
    "sessionId": "test-session"
  }'

常见问题

Q1: 启动后无法访问页面

症状：浏览器访问 http://服务器IP:3052 无响应

排查步骤：

检查服务是否启动：
```
docker-compose ps
```
检查端口是否被占用：
```
netstat -tunlp | grep 3052
```

检查防火墙：

# CentOS/RHEL
sudo firewall-cmd --add-port=3052/tcp --permanent
sudo firewall-cmd --reload

# Ubuntu
sudo ufw allow 3052

查看应用日志：
```
docker-compose logs app
```

Q2: 提示"agent 未初始化"

症状：使用 Nora 时返回错误 "agent 未初始化"

原因：LLM 或 Embedding API 配置有误

解决方案：

检查环境变量配置：

docker-compose exec app printenv | grep -E "EMBEDDING|ZHIPUAI"

验证 Embedding API 是否有效：

# 测试 OpenAI 兼容接口
curl $EMBEDDING_BASE_URL/embeddings \
  -H "Authorization: Bearer $EMBEDDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"text-embedding-3-small","input":"测试"}'

修正配置后重启：
```
docker-compose restart app
```

Q3: 提示"向量检索功能已禁用"

症状：日志显示 ⚠️ PG/pgvector 未可用，向量检索功能已禁用

影响：Nora 可以对话，但无法进行知识库检索

解决方案：

检查 PostgreSQL 服务：
```
docker-compose ps postgres
```

检查 pgvector 扩展：

docker-compose exec postgres psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS vector;"

重启应用：
```
docker-compose restart app
```

目录​

功能介绍​

系统要求​

外部 API 要求​

依赖服务​

外部 API​

快速部署​

1. 下载配置文件​

2. 配置环境变量​

3. 启动服务​

4. 等待初始化​

5. 访问系统​

配置说明​

基础环境变量​

功能验证​

1. 检查服务状态​

2. 检查应用日志​

3. 检查 PostgreSQL 向量扩展​

4. 测试 Nora 功能​

方法一：通过界面测试​

方法二：通过 API 测试​

常见问题​

Q1: 启动后无法访问页面​

Q2: 提示"agent 未初始化"​

Q3: 提示"向量检索功能已禁用"​

目录