Skip to content

Latest commit

 

History

History
219 lines (139 loc) · 19 KB

TROUBLESHOOTING.md

File metadata and controls

219 lines (139 loc) · 19 KB

การแก้ไขปัญหา

🌐 Languages: 🇺🇸 English | 🇧🇷 Português (Brasil) | 🇪🇸 Español | 🇫🇷 Français | 🇮🇹 Italiano | 🇷🇺 Русский | 🇨🇳 中文 (简体) | 🇩🇪 Deutsch | 🇮🇳 हिन्दी | 🇹🇭 ไทย | 🇺🇦 Українська | 🇸🇦 العربية | 🇯🇵 日本語 | 🇻🇳 Tiếng Việt | 🇧🇬 Български | 🇩🇰 Dansk | 🇫🇮 Suomi | 🇮🇱 עברית | 🇭🇺 Magyar | 🇮🇩 Bahasa Indonesia | 🇰🇷 한국어 | 🇲🇾 Bahasa Melayu | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇵🇹 Português (Portugal) | 🇷🇴 Română | 🇵🇱 Polski | 🇸🇰 Slovenčina | 🇸🇪 Svenska | 🇵🇭 Filipino

ปัญหาและวิธีแก้ปัญหาทั่วไปสำหรับ OmniRoute

แก้ไขด่วน

ปัญหา โซลูชั่น
การเข้าสู่ระบบครั้งแรกไม่ทำงาน ทำเครื่องหมาย INITIAL_PASSWORD ใน .env (ค่าเริ่มต้น: 123456)
แดชบอร์ดเปิดบนพอร์ตผิด ตั้งค่า PORT=20128 และ NEXT_PUBLIC_BASE_URL=http://localhost:20128
ไม่มีบันทึกคำขอภายใต้ logs/ ตั้งค่า ENABLE_REQUEST_LOGS=true
EACCES: การอนุญาตถูกปฏิเสธ ตั้งค่า DATA_DIR=/path/to/writable/dir เพื่อแทนที่ ~/.omniroute
กลยุทธ์การกำหนดเส้นทางไม่บันทึก อัปเดตเป็น v1.4.11+ (แก้ไข Zod schema สำหรับการคงอยู่ของการตั้งค่า)

ปัญหาของผู้ให้บริการ

"โมเดลภาษาไม่ได้ให้ข้อความ"

สาเหตุ: โควต้าของผู้ให้บริการหมดลง

แก้ไข:

  1. ตรวจสอบตัวติดตามโควต้าแดชบอร์ด
  2. ใช้คอมโบที่มีระดับทางเลือก
  3. เปลี่ยนไปใช้ระดับที่ถูกกว่า/ฟรี

การจำกัดอัตรา

สาเหตุ: โควต้าการสมัครใช้งานหมดลง

แก้ไข:

  • เพิ่มทางเลือก: cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking
  • ใช้ GLM/MiniMax เป็นข้อมูลสำรองราคาถูก

โทเค็น OAuth หมดอายุแล้ว

OmniRoute รีเฟรชโทเค็นอัตโนมัติ หากปัญหายังคงอยู่:

  1. แดชบอร์ด → ผู้ให้บริการ → เชื่อมต่อใหม่
  2. ลบและเพิ่มการเชื่อมต่อผู้ให้บริการอีกครั้ง

ปัญหาคลาวด์

ข้อผิดพลาดการซิงค์คลาวด์

  1. ตรวจสอบ BASE_URL ชี้ไปยังอินสแตนซ์ที่ทำงานอยู่ของคุณ (เช่น http://localhost:20128)
  2. ตรวจสอบ CLOUD_URL ชี้ไปยังจุดสิ้นสุดระบบคลาวด์ของคุณ (เช่น https://omniroute.dev)
  3. เก็บค่า NEXT_PUBLIC_* ให้สอดคล้องกับค่าฝั่งเซิร์ฟเวอร์

คลาวด์ stream=false ส่งคืน 500

อาการ: Unexpected token 'd'... บนจุดปลายทางคลาวด์สำหรับการโทรที่ไม่ใช่การสตรีม

สาเหตุ: อัปสตรีมส่งคืนเพย์โหลด SSE ในขณะที่ไคลเอ็นต์คาดหวัง JSON

วิธีแก้ปัญหา: ใช้ stream=true สำหรับการโทรโดยตรงบนคลาวด์ รันไทม์ในเครื่องรวมถึงทางเลือก SSE → JSON

Cloud บอกว่าเชื่อมต่อแล้ว แต่ "คีย์ API ไม่ถูกต้อง"

  1. สร้างคีย์ใหม่จากแดชบอร์ดในเครื่อง (/api/keys)
  2. เรียกใช้คลาวด์ซิงค์: เปิดใช้งานคลาวด์ → ซิงค์ทันที
  3. คีย์เก่า/ที่ไม่ได้ซิงค์ยังสามารถส่งคืน 401 บนคลาวด์ได้

ปัญหานักเทียบท่า

เครื่องมือ CLI แสดงว่าไม่ได้ติดตั้ง

  1. ตรวจสอบฟิลด์รันไทม์: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
  2. สำหรับโหมดพกพา: ใช้เป้าหมายรูปภาพ runner-cli (CLI ที่รวมกลุ่ม)
  3. สำหรับโหมดเมาต์โฮสต์: ตั้งค่า CLI_EXTRA_PATHS และเมาต์ไดเร็กทอรี bin โฮสต์เป็นแบบอ่านอย่างเดียว
  4. หาก installed=true และ runnable=false: พบไบนารีแต่ตรวจสุขภาพไม่สำเร็จ

การตรวจสอบรันไทม์ด่วน

curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'

ปัญหาต้นทุน

ต้นทุนสูง

  1. ตรวจสอบสถิติการใช้งานในแดชบอร์ด → การใช้งาน
  2. สลับโมเดลหลักเป็น GLM/MiniMax
  3. ใช้ Free Tier (Gemini CLI, iFlow) สำหรับงานที่ไม่สำคัญ
  4. กำหนดงบประมาณต้นทุนต่อคีย์ API: แดชบอร์ด → คีย์ API → งบประมาณ

การดีบัก

เปิดใช้งานบันทึกคำขอ

ตั้งค่า ENABLE_REQUEST_LOGS=true ในไฟล์ .env ของคุณ บันทึกจะปรากฏภายใต้ไดเรกทอรี logs/

ตรวจสอบสุขภาพของผู้ให้บริการ

# Health dashboard
http://localhost:20128/dashboard/health

# API health check
curl http://localhost:20128/api/monitoring/health

พื้นที่เก็บข้อมูลรันไทม์

  • สถานะหลัก: ${DATA_DIR}/db.json (ผู้ให้บริการ คอมโบ นามแฝง คีย์ การตั้งค่า)
  • การใช้งาน: ${DATA_DIR}/usage.json, ${DATA_DIR}/log.txt, ${DATA_DIR}/call_logs/
  • บันทึกคำขอ: <repo>/logs/... (เมื่อ ENABLE_REQUEST_LOGS=true)

ปัญหาเซอร์กิตเบรกเกอร์

ผู้ให้บริการติดอยู่ในสถานะเปิด

เมื่อเซอร์กิตเบรกเกอร์ของผู้ให้บริการเปิดอยู่ คำขอจะถูกบล็อกจนกว่าคูลดาวน์จะหมดลง

แก้ไข:

  1. ไปที่ แดชบอร์ด → การตั้งค่า → ความยืดหยุ่น
  2. ตรวจสอบการ์ดเซอร์กิตเบรกเกอร์สำหรับผู้ให้บริการที่ได้รับผลกระทบ
  3. คลิก รีเซ็ตทั้งหมด เพื่อล้างเบรกเกอร์ทั้งหมด หรือรอให้คูลดาวน์หมดลง
  4. ตรวจสอบว่าผู้ให้บริการพร้อมใช้งานจริงก่อนที่จะรีเซ็ต

ผู้ให้บริการสะดุดเบรกเกอร์อย่างต่อเนื่อง

หากผู้ให้บริการเข้าสู่สถานะเปิดซ้ำๆ:

  1. ตรวจสอบ แดชบอร์ด → สุขภาพ → สุขภาพของผู้ให้บริการ เพื่อดูรูปแบบความล้มเหลว
  2. ไปที่ การตั้งค่า → ความยืดหยุ่น → โปรไฟล์ผู้ให้บริการ และเพิ่มเกณฑ์ความล้มเหลว
  3. ตรวจสอบว่าผู้ให้บริการได้เปลี่ยนแปลงขีดจำกัด API หรือต้องมีการตรวจสอบสิทธิ์อีกครั้งหรือไม่
  4. ตรวจสอบการวัดและส่งข้อมูลทางไกลเวลาแฝง — เวลาแฝงสูงอาจทำให้เกิดความล้มเหลวตามการหมดเวลา

ปัญหาการถอดเสียง

ข้อผิดพลาด "รุ่นที่ไม่รองรับ"

  • ตรวจสอบให้แน่ใจว่าคุณใช้คำนำหน้าที่ถูกต้อง: deepgram/nova-3 หรือ assemblyai/best
  • ตรวจสอบว่าผู้ให้บริการเชื่อมต่ออยู่ใน Dashboard → Providers

การถอดเสียงกลับว่างเปล่าหรือล้มเหลว

  • ตรวจสอบรูปแบบเสียงที่รองรับ: mp3, wav, m4a, flac, ogg, webm
  • ตรวจสอบขนาดไฟล์อยู่ภายในขีดจำกัดของผู้ให้บริการ (โดยทั่วไปคือ <25MB)
  • ตรวจสอบความถูกต้องของคีย์ API ของผู้ให้บริการในการ์ดผู้ให้บริการ

การแก้ไขจุดบกพร่องของนักแปล

ใช้ แดชบอร์ด → ตัวแปล เพื่อแก้ไขปัญหาการแปลรูปแบบ:

| โหมด | เมื่อใดควรใช้ | | ---------------------- | ------------------------------------------------------------------------------------ | ------- | | สนามเด็กเล่น | เปรียบเทียบรูปแบบอินพุต/เอาต์พุตแบบเคียงข้างกัน — วางคำขอที่ล้มเหลวเพื่อดูว่าคำขอแปล | อย่างไร | | เครื่องมือทดสอบแชท | ส่งข้อความสดและตรวจสอบเพย์โหลดคำขอ/การตอบกลับทั้งหมด รวมถึงส่วนหัว | | ม้านั่งทดสอบ | เรียกใช้การทดสอบเป็นชุดระหว่างรูปแบบต่างๆ เพื่อดูว่าคำแปลใดเสียหาย | | ถ่ายทอดสด | ดูขั้นตอนคำขอแบบเรียลไทม์เพื่อตรวจจับปัญหาการแปลเป็นระยะๆ |

ปัญหารูปแบบทั่วไป

  • แท็กการคิดไม่ปรากฏ — ตรวจสอบว่าผู้ให้บริการเป้าหมายสนับสนุนการคิดและการตั้งค่างบประมาณการคิดหรือไม่
  • การเรียกเครื่องมือลดลง — การแปลรูปแบบบางรูปแบบอาจตัดช่องที่ไม่รองรับออก ตรวจสอบในโหมดสนามเด็กเล่น
  • การแจ้งเตือนของระบบหายไป — ระบบแจ้งของ Claude และ Gemini แตกต่างกัน ตรวจสอบผลลัพธ์การแปล
  • SDK ส่งคืนสตริงดิบแทนที่จะเป็นวัตถุ — แก้ไขในเวอร์ชัน 1.1.0: ตอนนี้ตัวล้างการตอบสนองจะตัดฟิลด์ที่ไม่ได้มาตรฐาน (x_groq, usage_breakdown ฯลฯ) ที่ทำให้การตรวจสอบ OpenAI SDK Pydantic ล้มเหลว
  • GLM/ERNIE ปฏิเสธบทบาท system — แก้ไขในเวอร์ชัน 1.1.0: บทบาท Normalizer จะรวมข้อความระบบเข้ากับข้อความผู้ใช้โดยอัตโนมัติสำหรับรุ่นที่เข้ากันไม่ได้
  • developer ไม่รู้จักบทบาท — แก้ไขใน v1.1.0: แปลงเป็น system โดยอัตโนมัติสำหรับผู้ให้บริการที่ไม่ใช่ OpenAI
  • json_schema ไม่ทำงานกับ Gemini — แก้ไขใน v1.1.0: response_format ตอนนี้ถูกแปลงเป็น responseMimeType + responseSchema ของ Gemini แล้ว

การตั้งค่าความยืดหยุ่น

ขีดจำกัดอัตราอัตโนมัติไม่ทริกเกอร์

  • การจำกัดอัตราอัตโนมัติใช้กับผู้ให้บริการคีย์ API เท่านั้น (ไม่ใช่ OAuth/การสมัครสมาชิก)
  • ตรวจสอบ การตั้งค่า → ความยืดหยุ่น → โปรไฟล์ผู้ให้บริการ ได้เปิดใช้งานการจำกัดอัตราอัตโนมัติแล้ว
  • ตรวจสอบว่าผู้ให้บริการส่งคืนรหัสสถานะ 429 หรือส่วนหัว Retry-After หรือไม่

การปรับแต่งการถอยกลับแบบเอ็กซ์โปเนนเชียล

โปรไฟล์ผู้ให้บริการรองรับการตั้งค่าเหล่านี้:

  • ความล่าช้าพื้นฐาน — เวลารอเริ่มต้นหลังจากความล้มเหลวครั้งแรก (ค่าเริ่มต้น: 1 วินาที)
  • ความล่าช้าสูงสุด — ขีดจำกัดเวลารอสูงสุด (ค่าเริ่มต้น: 30 วินาที)
  • ตัวคูณ — จะต้องเพิ่มความล่าช้าเท่าใดต่อความล้มเหลวติดต่อกัน (ค่าเริ่มต้น: 2x)

ฝูงต่อต้านฟ้าร้อง

เมื่อคำขอหลายรายการส่งถึงผู้ให้บริการที่จำกัดอัตรา OmniRoute จะใช้ mutex + การจำกัดอัตราอัตโนมัติเพื่อซีเรียลไลซ์คำขอและป้องกันความล้มเหลวแบบเรียงซ้อน นี่เป็นแบบอัตโนมัติสำหรับผู้ให้บริการคีย์ API

ยังติดอยู่เหรอ?

  • ปัญหา GitHub: github.com/diegosouzapw/OmniRoute/issues
  • สถาปัตยกรรม: ดู link สำหรับรายละเอียดภายใน
  • การอ้างอิง API: ดู link สำหรับจุดสิ้นสุดทั้งหมด
  • แดชบอร์ดสุขภาพ: ตรวจสอบ แดชบอร์ด → สุขภาพ เพื่อดูสถานะของระบบแบบเรียลไทม์
  • นักแปล: ใช้ แดชบอร์ด → นักแปล เพื่อแก้ไขปัญหาเกี่ยวกับรูปแบบ