Add debugging docs for AI/LiteLLM
This commit is contained in:
parent
5f341d694a
commit
5cf0303999
2 changed files with 128 additions and 85 deletions
109
CLAUDE.md
109
CLAUDE.md
|
|
@ -1,93 +1,34 @@
|
|||
# CLAUDE.md
|
||||
# AI Integration Debugging Guide
|
||||
|
||||
Tia - Baby Tracking App. Next.js 16, PostgreSQL, offline-first.
|
||||
|
||||
## Build Rule
|
||||
|
||||
**ALWAYS run `npm run build` before pushing.** Fix errors locally first.
|
||||
|
||||
## Project Status
|
||||
|
||||
- ✅ Fast-log (feed/sleep/diaper + offline queue)
|
||||
- ✅ PWA manifest + service worker
|
||||
- ✅ Vaccinations (IAP schedule)
|
||||
- ✅ Growth tracking
|
||||
- ✅ Memories gallery (placeholder)
|
||||
- ✅ AI chat (LiteLLM)
|
||||
- ✅ Dark mode toggle
|
||||
- ✅ Menu navigation
|
||||
- ⏳ Cloudflare R2 upload (needs credentials)
|
||||
- ⏳ Telegram alerts
|
||||
|
||||
## Key Files
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `src/app/page.tsx` | Home with quick log, dark mode toggle |
|
||||
| `src/app/menu/page.tsx` | Navigation drawer |
|
||||
| `src/app/medical/page.tsx` | IAP vaccination schedule |
|
||||
| `src/app/ai/page.tsx` | LiteLLM chat |
|
||||
| `src/app/api/logs/route.ts` | Feed/sleep/diaper logging |
|
||||
| `src/app/api/ai/route.ts` | LLM API proxy |
|
||||
| `src/db/schema/logs.ts` | Log schemas |
|
||||
| `public/sw.js` | Service worker for offline |
|
||||
|
||||
## Routes
|
||||
|
||||
- `/` - Home
|
||||
- `/menu` - Navigation
|
||||
- `/settings` - Settings + dark mode
|
||||
- `/medical` - Vaccinations
|
||||
- `/growth` - Growth records
|
||||
- `/memories` - Photo gallery
|
||||
- `/ai` - AI chat
|
||||
- `/api/logs` - Log entries (type=feed|sleep|diaper)
|
||||
- `/api/ai` - AI chat
|
||||
|
||||
## Conventions
|
||||
|
||||
### API Pattern
|
||||
```typescript
|
||||
// GET with query params, POST with JSON body
|
||||
export async function GET(request: Request) {
|
||||
const { searchParams } = new URL(request.url);
|
||||
const id = searchParams.get("id");
|
||||
// use sql.unsafe() for raw queries
|
||||
}
|
||||
export async function POST(request: Request) {
|
||||
const body = await request.json();
|
||||
// use sql.unsafe() with parameterized values
|
||||
}
|
||||
```
|
||||
|
||||
### UI Pattern
|
||||
```typescript
|
||||
"use client";
|
||||
import { useState, useEffect } from "react";
|
||||
// dark mode: document.documentElement.classList.toggle("dark")
|
||||
// links: use <Link href="..."> not router.push()
|
||||
```
|
||||
|
||||
### Database
|
||||
- Use `sql.unsafe()` not `db.execute()` - postgres-js method
|
||||
- Dates: `new Date().toISOString()` string format
|
||||
- Enums: create manually, no IF NOT EXISTS support
|
||||
|
||||
## Local Dev
|
||||
## Problem: "Invalid model name"
|
||||
|
||||
```bash
|
||||
cd tia
|
||||
npm run dev
|
||||
# Check available models
|
||||
curl -s "https://llm.manohargupta.com/v1/models" \
|
||||
-H "Authorization: Bearer sk-tiger-gateway-..."
|
||||
```
|
||||
|
||||
## Deployment
|
||||
Use model name from response: `minimax-2.7` (not `tiger-minimax`)
|
||||
|
||||
Auto-deploys via webhook on Git push. Database tables created via `/api/setup`.
|
||||
|
||||
## Environment
|
||||
## Problem: Empty response
|
||||
|
||||
Add debug logging and check server health:
|
||||
```bash
|
||||
curl -s "https://llm.manohargupta.com/health"
|
||||
```
|
||||
DATABASE_URL=postgresql://user:pass@host:5432/db
|
||||
OPENAI_API_BASE_URL=http://litellm-gateway:4000/v1
|
||||
LITELLM_MASTER_KEY=sk-tiger-gateway-...
|
||||
|
||||
## Problem: Network errors
|
||||
|
||||
- Use full domain: `https://llm.manohargupta.com` (not internal hostname)
|
||||
- Add `https://` prefix
|
||||
|
||||
## Test Script
|
||||
|
||||
```bash
|
||||
curl -s -X POST "https://llm.manohargupta.com/v1/chat/completions" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer sk-tiger-gateway-YOUR_KEY" \
|
||||
-d '{"model":"minimax-2.7","messages":[{"role":"user","content":"hi"}]}'
|
||||
```
|
||||
|
||||
See `/docs/debugging.md` for full guide.
|
||||
102
docs/debugging.md
Normal file
102
docs/debugging.md
Normal file
|
|
@ -0,0 +1,102 @@
|
|||
# AI/LiteLLM Debugging Guide
|
||||
|
||||
## Debugging AI Integration Issues
|
||||
|
||||
### Problem: "Invalid model name" error
|
||||
|
||||
```json
|
||||
{"error":{"message":"/chat/completions: Invalid model name passed in model=gpt-4o-mini.
|
||||
Call `/v1/models` to view available models for your key.","type":"None","param":"None","code":"400"}}
|
||||
```
|
||||
|
||||
**Debugging Steps:**
|
||||
|
||||
1. **Check available models:**
|
||||
```bash
|
||||
curl -s "https://YOUR_LITELLM_URL/v1/models" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY"
|
||||
```
|
||||
|
||||
2. **Use correct model name from response** - model names like `minimax-2.7`, not `tiger-minimax` etc.
|
||||
|
||||
### Problem: "login fail" error
|
||||
|
||||
```json
|
||||
{"base_resp":{"status_code":1004,"status_msg":"login fail: Please carry the API secret key
|
||||
in the 'Authorization' field of the request header"}}
|
||||
```
|
||||
|
||||
**Causes:**
|
||||
- Wrong API key format
|
||||
- Invalid API key
|
||||
- Key not configured in LiteLLM
|
||||
|
||||
**Debugging Steps:**
|
||||
|
||||
1. Test API key directly:
|
||||
```bash
|
||||
curl -s -X POST "https://api.minimax.chat/v1/text/chatcompletion_v2" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_KEY" \
|
||||
-d '{"model":"abab7.5-chat","messages":[{"role":"user","content":"hi"}]}'
|
||||
```
|
||||
|
||||
### Problem: Empty response
|
||||
|
||||
**Error:**
|
||||
```json
|
||||
{"reply":"Sorry, I couldn't get a response."}
|
||||
```
|
||||
|
||||
**Debugging Steps:**
|
||||
|
||||
1. Add debug logging:
|
||||
```typescript
|
||||
const data = await response.json();
|
||||
console.log("API response:", data);
|
||||
return NextResponse.json({ reply: data.choices?.[0]?.message?.content });
|
||||
```
|
||||
|
||||
2. Check server health:
|
||||
```bash
|
||||
curl -s "https://YOUR_LITELLM_URL/health"
|
||||
```
|
||||
|
||||
### Problem: Network errors (fetch failed)
|
||||
|
||||
**Debug:**
|
||||
1. Check URL accessibility from deployed server
|
||||
2. Use full domain, not internal hostname: `https://llm.manohargupta.com` not `http://litellm-gateway:4000`
|
||||
3. Add `https://` prefix
|
||||
|
||||
## LiteLLM URL Pattern
|
||||
|
||||
```
|
||||
https://llm.manohargupta.com/v1/chat/completions
|
||||
```
|
||||
|
||||
Expected models from LiteLLM:
|
||||
- `minimax-2.7`
|
||||
- `minimax-2.7-fast`
|
||||
- `claude-haiku`
|
||||
- `claude-sonnet`
|
||||
- `nvidia-llama`
|
||||
|
||||
## API Key Format
|
||||
|
||||
For LiteLLM:
|
||||
- Key: `sk-tiger-gateway-...` (your key)
|
||||
- Header: `Authorization: Bearer sk-tiger-gateway-...`
|
||||
|
||||
For MiniMax direct:
|
||||
- Different key format - check platform.minimax.ai
|
||||
|
||||
## Test Script
|
||||
|
||||
```bash
|
||||
# Test LiteLLM
|
||||
curl -s -X POST "https://llm.manohargupta.com/v1/chat/completions" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer sk-tiger-gateway-YOUR_KEY" \
|
||||
-d '{"model":"minimax-2.7","messages":[{"role":"user","content":"hi"}]}'
|
||||
```
|
||||
Loading…
Add table
Reference in a new issue