大模型应用开发 / 系统课时
实现知识问答后端
实现知识问答后端
学习目标
完成本课后,你将能够:
- 使用 FastAPI 实现文档导入、健康检查和问答接口
- 调用 Ollama 嵌入与对话 API 完成 RAG 链路
- 实现文本切分、余弦相似度、阈值过滤和来源返回
- 将索引持久化到本地 JSON 文件并完成端到端验证
项目目录
创建目录:
bash
mkdir -p ollama-knowledge-api
cd ollama-knowledge-api预期结果:
text
进入空的 ollama-knowledge-api 目录。项目包含:
text
ollama-knowledge-api/
├── app.py
├── requirements.txt
└── data/
└── index.jsonindex.json 会在首次导入文档时自动创建。
安装依赖
创建 requirements.txt:
text
fastapi>=0.115,<1.0
uvicorn[standard]>=0.30,<1.0
pydantic>=2.8,<3.0创建虚拟环境并安装:
bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt预期结果:
text
依赖安装完成,没有 unresolved dependency 或 installation failed 错误。完整后端代码
创建 app.py:
python
from __future__ import annotations
import hashlib
import json
import math
import os
import threading
import urllib.error
import urllib.request
import uuid
from pathlib import Path
from typing import Any
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
OLLAMA_BASE_URL = os.getenv(
"OLLAMA_BASE_URL", "http://localhost:11434"
).rstrip("/")
GENERATION_MODEL = os.getenv("GENERATION_MODEL", "<GENERATION_MODEL>")
EMBEDDING_MODEL = os.getenv("EMBEDDING_MODEL", "<EMBEDDING_MODEL>")
INDEX_PATH = Path(os.getenv("INDEX_PATH", "data/index.json"))
CHUNK_SIZE = int(os.getenv("CHUNK_SIZE", "700"))
CHUNK_OVERLAP = int(os.getenv("CHUNK_OVERLAP", "120"))
MIN_SCORE = float(os.getenv("MIN_SCORE", "0.25"))
REQUEST_TIMEOUT = float(os.getenv("REQUEST_TIMEOUT", "180"))
app = FastAPI(title="Ollama Local Knowledge API", version="1.0.0")
index_lock = threading.Lock()
class DocumentRequest(BaseModel):
source: str = Field(min_length=1, max_length=300)
title: str = Field(min_length=1, max_length=300)
text: str = Field(min_length=1, max_length=2_000_000)
class AskRequest(BaseModel):
question: str = Field(min_length=1, max_length=10_000)
top_k: int = Field(default=4, ge=1, le=12)
def ollama_post(path: str, payload: dict[str, Any]) -> dict[str, Any]:
request = urllib.request.Request(
f"{OLLAMA_BASE_URL}{path}",
data=json.dumps(payload).encode("utf-8"),
headers={"Content-Type": "application/json"},
method="POST",
)
try:
with urllib.request.urlopen(
request, timeout=REQUEST_TIMEOUT
) as response:
return json.loads(response.read().decode("utf-8"))
except urllib.error.HTTPError as exc:
detail = exc.read().decode("utf-8", errors="replace")
raise HTTPException(
status_code=502,
detail=f"Ollama returned HTTP {exc.code}: {detail}",
) from exc
except (urllib.error.URLError, TimeoutError) as exc:
raise HTTPException(
status_code=503,
detail=f"Cannot reach Ollama: {exc}",
) from exc
def load_index() -> dict[str, Any]:
if not INDEX_PATH.exists():
return {
"embedding_model": EMBEDDING_MODEL,
"chunks": [],
}
data = json.loads(INDEX_PATH.read_text(encoding="utf-8"))
stored_model = data.get("embedding_model")
if stored_model != EMBEDDING_MODEL:
raise RuntimeError(
"Index embedding model mismatch: "
f"stored={stored_model}, configured={EMBEDDING_MODEL}"
)
return data
def save_index(data: dict[str, Any]) -> None:
INDEX_PATH.parent.mkdir(parents=True, exist_ok=True)
temporary = INDEX_PATH.with_suffix(".tmp")
temporary.write_text(
json.dumps(data, ensure_ascii=False),
encoding="utf-8",
)
temporary.replace(INDEX_PATH)
def normalize_text(text: str) -> str:
lines = [line.strip() for line in text.replace("\r\n", "\n").split("\n")]
return "\n".join(line for line in lines if line)
def split_text(text: str) -> list[str]:
cleaned = normalize_text(text)
if len(cleaned) <= CHUNK_SIZE:
return [cleaned]
chunks: list[str] = []
start = 0
while start < len(cleaned):
end = min(start + CHUNK_SIZE, len(cleaned))
if end < len(cleaned):
paragraph_break = cleaned.rfind("\n", start, end)
sentence_break = max(
cleaned.rfind("。", start, end),
cleaned.rfind("!", start, end),
cleaned.rfind("?", start, end),
)
candidate = max(paragraph_break, sentence_break)
if candidate > start + CHUNK_SIZE // 2:
end = candidate + 1
chunk = cleaned[start:end].strip()
if chunk:
chunks.append(chunk)
if end >= len(cleaned):
break
start = max(end - CHUNK_OVERLAP, start + 1)
return chunks
def embed_texts(texts: list[str]) -> list[list[float]]:
response = ollama_post(
"/api/embed",
{
"model": EMBEDDING_MODEL,
"input": texts,
},
)
embeddings = response.get("embeddings")
if not isinstance(embeddings, list) or len(embeddings) != len(texts):
raise HTTPException(
status_code=502,
detail="Unexpected embedding response from Ollama",
)
return embeddings
def cosine_similarity(left: list[float], right: list[float]) -> float:
if len(left) != len(right):
raise ValueError("Embedding dimensions do not match")
dot = sum(a * b for a, b in zip(left, right))
left_norm = math.sqrt(sum(value * value for value in left))
right_norm = math.sqrt(sum(value * value for value in right))
if left_norm == 0 or right_norm == 0:
return 0.0
return dot / (left_norm * right_norm)
def search_index(
question_embedding: list[float],
top_k: int,
) -> list[dict[str, Any]]:
with index_lock:
index = load_index()
chunks = list(index["chunks"])
scored: list[dict[str, Any]] = []
for chunk in chunks:
score = cosine_similarity(
question_embedding,
chunk["embedding"],
)
if score >= MIN_SCORE:
scored.append({
"chunk_id": chunk["chunk_id"],
"source": chunk["source"],
"title": chunk["title"],
"text": chunk["text"],
"score": score,
})
scored.sort(key=lambda item: item["score"], reverse=True)
return scored[:top_k]
def build_context(matches: list[dict[str, Any]]) -> str:
sections = []
for index, match in enumerate(matches, start=1):
sections.append(
f"[资料 {index}]\n"
f"来源:{match['source']}\n"
f"内容:{match['text']}"
)
return "\n\n".join(sections)
@app.get("/health")
def health() -> dict[str, Any]:
tags = urllib.request.urlopen(
f"{OLLAMA_BASE_URL}/api/tags",
timeout=10,
)
return {
"status": "ok",
"ollama_status": tags.status,
"generation_model": GENERATION_MODEL,
"embedding_model": EMBEDDING_MODEL,
"index_path": str(INDEX_PATH),
}
@app.post("/documents")
def add_document(request: DocumentRequest) -> dict[str, Any]:
chunks = split_text(request.text)
embeddings = embed_texts(chunks)
document_hash = hashlib.sha256(
request.text.encode("utf-8")
).hexdigest()
records = []
for position, (text, embedding) in enumerate(
zip(chunks, embeddings),
start=1,
):
records.append({
"chunk_id": f"{document_hash[:12]}-{position:04d}",
"document_hash": document_hash,
"source": request.source,
"title": request.title,
"text": text,
"embedding": embedding,
})
with index_lock:
index = load_index()
index["chunks"] = [
chunk
for chunk in index["chunks"]
if chunk.get("document_hash") != document_hash
]
index["chunks"].extend(records)
save_index(index)
return {
"source": request.source,
"document_hash": document_hash,
"chunks_added": len(records),
"embedding_model": EMBEDDING_MODEL,
}
@app.post("/ask")
def ask(request: AskRequest) -> dict[str, Any]:
request_id = str(uuid.uuid4())
question_embedding = embed_texts([request.question])[0]
matches = search_index(question_embedding, request.top_k)
if not matches:
return {
"request_id": request_id,
"answer": "当前资料中没有足够信息回答该问题。",
"sources": [],
"model": GENERATION_MODEL,
"retrieval_model": EMBEDDING_MODEL,
}
context = build_context(matches)
response = ollama_post(
"/api/chat",
{
"model": GENERATION_MODEL,
"stream": False,
"messages": [
{
"role": "system",
"content": (
"你是本地知识助手。只根据提供的资料回答。"
"资料不足时必须明确说明无法从当前资料确定。"
"不要编造来源。"
),
},
{
"role": "user",
"content": (
f"资料:\n{context}\n\n"
f"问题:{request.question}"
),
},
],
},
)
message = response.get("message") or {}
answer = message.get("content")
if not isinstance(answer, str):
raise HTTPException(
status_code=502,
detail="Unexpected chat response from Ollama",
)
return {
"request_id": request_id,
"answer": answer,
"sources": [
{
"chunk_id": item["chunk_id"],
"source": item["source"],
"title": item["title"],
"score": round(item["score"], 6),
"text": item["text"],
}
for item in matches
],
"model": GENERATION_MODEL,
"retrieval_model": EMBEDDING_MODEL,
}代码使用标准库调用 Ollama,不依赖额外 HTTP 客户端。索引写入临时文件后原子替换,降低写入中断造成文件损坏的概率。
配置并启动
先确保生成模型和嵌入模型已经下载。设置环境变量:
bash
export GENERATION_MODEL=<GENERATION_MODEL>
export EMBEDDING_MODEL=<EMBEDDING_MODEL>
export OLLAMA_BASE_URL=http://localhost:11434
export INDEX_PATH=data/index.json
export CHUNK_SIZE=700
export CHUNK_OVERLAP=120
export MIN_SCORE=0.25启动:
bash
uvicorn app:app --host 127.0.0.1 --port 8000预期输出中应包含:
text
Uvicorn running on http://127.0.0.1:8000实际日志还会显示进程 ID 和启动时间。
验证健康检查
另开终端:
bash
curl --fail --silent --show-error http://127.0.0.1:8000/health预期响应结构:
json
{
"status": "ok",
"ollama_status": 200,
"generation_model": "<GENERATION_MODEL>",
"embedding_model": "<EMBEDDING_MODEL>",
"index_path": "data/index.json"
}若返回 503 或连接错误,先检查 Ollama 服务和两个模型名称。
导入测试文档
创建请求:
bash
curl http://127.0.0.1:8000/documents -H 'Content-Type: application/json' -d '{
"source": "deployment-policy.txt",
"title": "部署规范",
"text": "知识助手默认只允许内网访问。生产环境必须通过反向代理提供 HTTPS 和身份认证。模型服务端口不得直接暴露到公网。"
}'预期 HTTP 结果:
text
状态码 200。响应体包含 source、document_hash、chunks_added 和 embedding_model。chunks_added 应大于或等于 1。检查索引文件:
bash
python3 -m json.tool data/index.json | head -n 40预期输出:
text
显示 embedding_model 和 chunks 数组,每个块包含来源、原文和 embedding。完成资料内问答
提问:
bash
curl http://127.0.0.1:8000/ask -H 'Content-Type: application/json' -d '{
"question": "生产环境如何保护知识助手接口?",
"top_k": 3
}'预期 HTTP 结果:
text
状态码 200。answer 应基于测试文档提到 HTTPS、身份认证和避免公网直暴;sources 至少包含 deployment-policy.txt。模型措辞和相似度分数会变化。验证资料外拒答
提问未出现在资料中的内容:
bash
curl http://127.0.0.1:8000/ask -H 'Content-Type: application/json' -d '{
"question": "公司的年假有多少天?",
"top_k": 3
}'预期结果:
text
如果没有文本块达到 MIN_SCORE,answer 为“当前资料中没有足够信息回答该问题。”且 sources 为空。若错误检索到测试文档,应提高阈值或改进检索评测。实现限制与下一步
当前实现适合教学和小数据验证,仍有以下限制:
- JSON 索引使用线性扫描,数据量增大后速度下降。
- 进程内线程锁不能协调多个后端实例。
- 文档按字符切分,不是 Token 级预算。
- 没有用户认证和来源权限过滤。
/ask使用非流式输出。- 没有增量删除、版本和后台索引任务。
- 健康检查只验证 API,不验证模型能否完成推理。
- 相似度阈值需要通过业务数据校准。
下一步部署前,应增加认证、限流、超时、日志、持久卷和反向代理。
本课练习
练习 1:导入两份文档
任务目标:验证来源可追溯。输入或初始条件:准备主题不同的两段文本。
实现要求:分别调用 /documents 后对两者提问
验收条件:每个回答的 sources 指向正确文件。
练习 2:校准相似度阈值
任务目标:减少资料外误匹配。输入或初始条件:准备 20 个资料内问题和 20 个资料外问题。实现要求:比较多个 MIN_SCORE。验收条件:选择兼顾召回与拒答的阈值并记录依据。
练习 3:验证索引模型保护
任务目标:避免不同嵌入模型混用。输入或初始条件:已生成一个索引文件。
实现要求:修改 EMBEDDING_MODEL 后重启。验收条件:系统明确报模型不匹配,而不是继续检索。
按自己的节奏,确认真正理解。