Revel框架仅负责HTTP层路由、参数校验与错误包装，AI逻辑（切分、嵌入、检索、生成）须交由外部服务或Go库处理；用户提问必须通过POST /api/ask的JSON body传入，需定义带validate标签的AskRequest结构体校验；禁止在控制器中直调embedding API以防goroutine阻塞；响应须包含可追溯的sources字段，明确标注DocID、PageNum、Text及Score；Swagger注释需体现语义约束，如@Failure 422标识“检索无结果”而非系统错误。
Revel 框架本身不提供向量检索、文档解析或 LLM 调用能力，构建智能知识库问答接口的关键是：用 Revel 做好 HTTP 层的路由、参数校验、状态码返回和错误包装，把 AI 相关逻辑（切分、嵌入、检索、生成）交给外部服务或本地 Go 库完成。
Revel 中如何接收并校验用户提问
用户问题必须作为 POST /api/ask 的 JSON body 传入，不能放在 query 或 form 中——否则无法支持长问题、特殊字符和历史上下文字段。Revel 的 c.Params.Body 可直接读取原始字节，但更稳妥的做法是定义结构体并用 c.Params.JSON 解析：
type AskRequest struct {
Question string `json:"question" validate:"required,min=2,max=2000"`
SessionID string `json:"session_id,omitempty"`
TopK int `json:"top_k,omitempty"`
}
注意三点：
-
validate标签需配合 Revel 的validation模块启用，否则不起作用 -
TopK默认应设为 3～5，太大易拖慢响应，太小可能漏掉关键段落 - 若需支持多轮对话，
session_id必须由前端生成并透传，Revel 不自动维护会话上下文
为什么不能在 Revel 控制器里直接调用 embedding API
因为 Revel 默认使用同步阻塞模型，而 embedding 请求（尤其是调用远程 API 如 DashScope 或 Qwen）平均耗时 300–800ms，若在控制器中直连，会卡住整个 Goroutine，导致并发能力骤降。正确做法是：
- 将 embedding 和检索逻辑封装成独立的 Go 包（如
pkg/retriever），内部用context.WithTimeout控制单次调用上限 - 在 Revel 控制器中只做轻量级调度，例如：
result, err := retriever.Query(ctx, req.Question, req.TopK) - 避免在
AppController方法里写http.Post或embedder.Embed()这类 I/O 密集操作
否则上线后稍有流量就会触发 Revel 的 goroutine leak 报警，日志里反复出现 http: Accept error: accept tcp: too many open files。
如何让问答结果带可追溯的原文引用
企业级知识库必须回答“这个结论来自哪段原文”，不能只返回自然语言答案。Revel 接口需在响应体中显式包含 sources 字段：
type AskResponse struct {
Answer string `json:"answer"`
Sources []SourceItem `json:"sources"`
}
type SourceItem struct {
DocID string `json:"doc_id"`
PageNum int `json:"page_num"`
Text string `json:"text"`
Score float64 `json:"score"`
}
关键点：
-
DocID必须与上传文档时生成的唯一标识一致（如文件哈希 + 时间戳），不能用文件名，否则重名覆盖后引用失效 -
Score是向量相似度得分，不是百分比，范围通常在 0.4–0.9 之间，低于 0.5 的结果应过滤或降权 - 若检索未命中任何段落，
Answer应明确写“未找到相关资料”，而非让 LLM 自由发挥
Swagger 文档怎么体现知识库问答的语义约束
Revel 不原生支持 Swagger，但通过 swaggo/swag 注释能准确描述问答接口的业务语义。重点不是罗列字段，而是用注释表达约束：
// @Summary 执行知识库语义问答
// @Description 仅检索已启用且当前有效的文档片段；若无匹配内容，返回空数组而非幻觉答案
// @Accept json
// @Produce json
// @Param request body AskRequest true "提问请求体"
// @Success 200 {object} AskResponse "答案及对应原文片段"
// @Failure 400 {object} ErrorResponse "参数缺失或超出长度限制"
// @Failure 422 {object} ErrorResponse "检索无结果，且未启用兜底生成"
// @Router /api/ask [post]
这里 @Failure 422 很关键——它把“知识不可用”从“系统错误”中剥离出来，前端可据此展示“暂无相关信息”而不是报错弹窗。很多团队忽略这点，导致用户以为系统坏了，其实是知识源没覆盖到该问题。
真正难的不是写通一个问答接口，而是让每次 /api/ask 返回的答案都经得起追问：“你凭什么这么说？”这要求从文档入库时就打上有效性标签，检索时做过滤，响应时带出处。Revel 只管把这条路铺平，别让它变成黑盒通道。
