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.
|
## Problem: "Invalid model name"
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd tia
|
# Check available models
|
||||||
npm run dev
|
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`.
|
## Problem: Empty response
|
||||||
|
|
||||||
## Environment
|
|
||||||
|
|
||||||
|
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
|
## Problem: Network errors
|
||||||
LITELLM_MASTER_KEY=sk-tiger-gateway-...
|
|
||||||
|
- 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