Merge pull request #151 from ql-link/claude/api-log-coverage

feat(logging): 补核心 API 与 recall pipeline 的日志覆盖

Author: jixua

src/api/routes/internal.py

@@ -7,6 +7,7 @@
 from datetime import datetime
 
 from fastapi import APIRouter, Header, HTTPException, Depends
+from loguru import logger
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.core.llm.response import APIResponse
@@ -54,6 +55,7 @@ async def get_system_providers(
         )
 
     except Exception as e:
+        logger.exception("/internal/llm 接口调用失败")
         return APIResponse(code=500, message=str(e), data=None)
 
 
@@ -97,6 +99,7 @@ async def get_user_configs(
         )
 
     except Exception as e:
+        logger.exception("/internal/llm 接口调用失败")
         return APIResponse(code=500, message=str(e), data=None)
 
 
@@ -134,4 +137,5 @@ async def get_user_usage(
         )
 
     except Exception as e:
+        logger.exception("/internal/llm 接口调用失败")
         return APIResponse(code=500, message=str(e), data=None)

src/api/routes/llm.py

@@ -5,6 +5,7 @@
 from typing import Optional, List
 
 from fastapi import APIRouter, Header, HTTPException, Depends
+from loguru import logger
 from pydantic import BaseModel, Field
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -139,6 +140,7 @@ async def generate_text(
     except HTTPException:
         raise
     except Exception as e:
+        logger.exception(f"/llm/generate 调用失败 (user={x_user_id})")
         return APIResponse(
             code=500,
             message=str(e),
@@ -183,6 +185,7 @@ async def event_generator():
     except HTTPException:
         raise
     except Exception as e:
+        logger.exception(f"/llm 接口调用失败 (user={x_user_id})")
         return APIResponse(code=500, message=str(e), data=None)
 
 
@@ -214,6 +217,7 @@ async def embed_text(
     except HTTPException:
         raise
     except Exception as e:
+        logger.exception(f"/llm 接口调用失败 (user={x_user_id})")
         return APIResponse(code=500, message=str(e), data=None)
 
 
@@ -250,6 +254,7 @@ async def rerank_documents(
     except HTTPException:
         raise
     except Exception as e:
+        logger.exception(f"/llm 接口调用失败 (user={x_user_id})")
         return APIResponse(code=500, message=str(e), data=None)
 
 
@@ -283,4 +288,5 @@ async def extract_text_from_image(
     except HTTPException:
         raise
     except Exception as e:
+        logger.exception(f"/llm 接口调用失败 (user={x_user_id})")
         return APIResponse(code=500, message=str(e), data=None)

src/api/routes/parse.py

@@ -8,6 +8,7 @@
 from pathlib import Path
 
 from fastapi import APIRouter, UploadFile, File, Form, HTTPException
+from loguru import logger
 
 from src.config import settings
 from src.services.parse_task_service import ParseTaskService
@@ -87,6 +88,7 @@ async def extract_sync(
             "time_cost_ms": result["time_cost_ms"],
         }
     except Exception as e:
+        logger.exception("/parser 接口处理失败")
         raise HTTPException(status_code=500, detail=str(e))
     finally:
         temp_workspace.safe_unlink(upload_path)
@@ -130,4 +132,5 @@ async def submit_async_task(request: TaskSubmitRequest):
             },
         )
     except Exception as e:
+        logger.exception("/parser 接口处理失败")
         raise HTTPException(status_code=500, detail=str(e))

src/core/pipeline/recall/pipeline.py

@@ -68,6 +68,16 @@ async def execute(self, request: RecallRequest) -> RecallResponse:
         started_at = time.monotonic()
         self._validate(request)
 
+        # 入口日志：不记 query 原文（可能含用户敏感内容），只记可观测的元信息。
+        logger.info(
+            "[RecallPipeline] start user={} datasets={} docs={} top_k={} mode={}",
+            request.user_id,
+            len(request.dataset_ids or []),
+            len(request.doc_ids or []),
+            request.top_k,
+            "parallel" if self._config.parallel else "serial",
+        )
+
         if self._config.parallel:
             per_source_results = await self._run_parallel(request)
         else:
@@ -82,6 +92,16 @@ async def execute(self, request: RecallRequest) -> RecallResponse:
         # 服务端固定返回候选上限：融合后按 top_k 截断（fuse 已按 fused_score 降序）。
         fused_hits = fused_hits[: request.top_k]
         elapsed_ms = int((time.monotonic() - started_at) * 1000)
+
+        # 结果日志：耗时、融合命中数、各路命中分布、失败路（已有数据，原先只进响应不落日志）。
+        logger.info(
+            "[RecallPipeline] done user={} elapsed_ms={} hits={} per_source={} failed={}",
+            request.user_id,
+            elapsed_ms,
+            len(fused_hits),
+            {s: len(success_hits.get(s, [])) for s in self._sources},
+            failed_sources,
+        )
         return self._build_response(
             query=request.query,
             fused_hits=fused_hits,

src/main.py

@@ -108,6 +108,11 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
 @app.exception_handler(RecallApiError)
 async def recall_api_error_handler(request: Request, exc: RecallApiError) -> JSONResponse:
     """内部召回握手前错误统一响应：{code, message, data} + 对应 HTTP 状态。"""
+    # 握手失败（鉴权 / 入参 / 限流等）记 warning：便于排查对接问题与发现异常调用。
+    logger.warning(
+        f"召回握手失败 {request.method} {request.url.path}: "
+        f"code={exc.code} status={exc.status_code} msg={exc.message}"
+    )
     return JSONResponse(
         status_code=exc.status_code,
         content={"code": exc.code, "message": exc.message, "data": None},