SSD Nodes Learn Hosting plans →
คู่มือ Matt Connorโดย Matt Connor

วิธีติดตั้ง LiteLLM เป็น LLM Gateway บนเซิร์ฟเวอร์ตัวเอง

เรียนรู้วิธีติดตั้ง LiteLLM เพื่อรวม API จากทุกผู้ให้บริการไว้ในจุดเดียว รองรับการจัดการ Virtual keys การกำหนดงบประมาณต่อคีย์ และระบบ Fallback สำหรับ OpenAI compatible endpoint

หน้าที่ของ LLM gateway แบบ self-hosted

LiteLLM คือ LLM gateway แบบ open source ที่คุณโฮสต์ด้วยตนเอง โดยทำหน้าที่เป็น HTTP endpoint เดียวที่แอปพลิเคชันทั้งหมดของคุณเรียกใช้งาน จากนั้น gateway จะส่งต่อคำขอแต่ละรายการไปยังผู้ให้บริการที่เหมาะสม LLM ย่อมาจาก large language model ตัว gateway นี้รองรับ OpenAI chat completions API (application programming interface) ดังนั้น client library ใดก็ตามที่สื่อสารกับ OpenAI อยู่แล้วจะสามารถใช้งานร่วมกับ gateway นี้ได้ทันทีหลังจากปรับเปลี่ยน 2 จุด คือ base URL และ key

การเพิ่มชั้นการทำงานนี้ขึ้นมาคือหัวใจสำคัญ แอปพลิเคชันของคุณไม่จำเป็นต้องเก็บข้อมูลรับรอง (credentials) ของผู้ให้บริการอีกต่อไป การเปลี่ยนโมเดลสามารถทำได้โดยแก้ไขบรรทัดเดียวในไฟล์ config บนเซิร์ฟเวอร์ แทนที่จะต้องแก้ไขโค้ดใน 5 บริการ และเนื่องจากทุกการเรียกใช้งานผ่านกระบวนการเดียว คุณจึงมีจุดศูนย์กลางสำหรับกำหนดงบประมาณและบันทึกค่าใช้จ่ายที่เกิดขึ้น

นี่คือสิ่งที่คุณจะได้รับเมื่อระบบเริ่มทำงาน:

  • Endpoint เดียว: แอปพลิเคชันจะชี้เป้าไปที่ https://gateway.example.com/v1 และระบุชื่อโมเดลที่คุณกำหนดขึ้นเอง เช่น bulk หรือ strong
  • Virtual keys: แต่ละแอปพลิเคชันจะได้รับ key ของตนเอง พร้อมรายการโมเดลที่อนุญาตให้ใช้และเพดานงบประมาณเฉพาะตัว คุณสามารถเพิกถอนสิทธิ์ของแอปหนึ่งได้โดยไม่กระทบแอปอื่น
  • Fallbacks: หากการเรียกใช้งานล้มเหลวหรือ prompt มีขนาดใหญ่เกินไป ระบบจะลองเรียกใช้โมเดลอื่นโดยอัตโนมัติ
  • บันทึกการใช้งาน: ทุกคำขอจะถูกบันทึกพร้อมระบุต้นทุน ทำให้สามารถตรวจสอบได้ว่า "แอปใดเป็นผู้ใช้จ่ายงบประมาณนั้น"

เหตุผลที่ควรจัดการเกตเวย์ด้วยตนเอง

Managed router มีลักษณะการทำงานเหมือนกัน แต่มีกระบวนการของผู้อื่นแทรกอยู่ตรงกลางในทุกคำขอ การจัดการด้วยตนเองช่วยให้กุญแจของผู้ให้บริการและข้อความ prompt ของคุณอยู่บนเครื่องที่คุณควบคุมได้จริง อย่างไรก็ตาม ต้นทุนที่ต้องแลกมานั้นมีอยู่จริง คือคุณต้องเป็นผู้ดูแลส่วนประกอบที่ทุกแอปพลิเคชันต้องพึ่งพา ส่วนสุดท้ายของคู่มือนี้จะกล่าวถึงต้นทุนดังกล่าว เนื่องจากเป็นส่วนที่บทความส่วนใหญ่มักละเลยไป

สิ่งที่ต้องเตรียม

  • VPS (virtual private server) ที่รัน Ubuntu 24.04 พร้อมติดตั้ง Docker และ Compose plugin
  • โดเมนเนมที่ชี้มายังเซิร์ฟเวอร์ หากต้องการให้เครื่องภายนอกเข้าถึง gateway ผ่าน TLS (transport layer security)
  • API key ของผู้ให้บริการอย่างน้อยหนึ่งรายการ

Gateway ไม่ได้ทำหน้าที่ประมวลผล inference โดยตรง แต่ทำหน้าที่ส่งต่อคำขอและสตรีมคำตอบกลับมา ดังนั้นภาระงานของ CPU จะขึ้นอยู่กับปริมาณคำขอมากกว่าขนาดของโมเดล เซิร์ฟเวอร์ขนาด 1 vCPU สามารถรองรับแอปพลิเคชันภายในจำนวนหนึ่งได้โดยไม่มีปัญหา สิ่งที่จะเพิ่มขึ้นตามการใช้งานคือฐานข้อมูล เนื่องจาก gateway จะบันทึกแถวข้อมูลค่าใช้จ่ายต่อหนึ่งคำขอ

เขียนไฟล์ config.yaml ก่อน

ไฟล์ config เป็นตัวกำหนดว่าไคลเอนต์สามารถเรียกใช้โมเดลใดได้บ้าง โดยมีส่วนประกอบหลัก 4 ส่วนที่สำคัญ ได้แก่ model_list, litellm_settings, router_settings และ general_settings

model_list:
  - model_name: bulk
    litellm_params:
      model: anthropic/claude-haiku-4-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: strong
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: strong
    litellm_params:
      model: openai/gpt-5.5
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  num_retries: 2
  request_timeout: 120
  json_logs: true
  set_verbose: false

router_settings:
  allowed_fails: 3
  cooldown_time: 30
  fallbacks: [{"bulk": ["strong"]}]
  context_window_fallbacks: [{"bulk": ["strong"]}]

general_settings:
  background_health_checks: true
  health_check_interval: 300

model_name คือชื่อที่ไคลเอนต์ของคุณใช้ส่งคำขอ ส่วน litellm_params.model คือชื่อโมเดลจริงที่เขียนในรูปแบบ provider/model ควรตั้งชื่อโมเดลตามลักษณะงานแทนที่จะตั้งตามชื่อผู้ให้บริการ แอปพลิเคชันที่เรียกใช้ bulk จะยังคงทำงานได้ตามปกติแม้ในเดือนถัดไปคุณจะตัดสินใจเปลี่ยนให้ bulk ไปใช้โมเดลอื่นแทนก็ตาม

api_key: os.environ/ANTHROPIC_API_KEY สั่งให้ LiteLLM อ่านค่าตัวแปรนั้นในขณะรันไทม์ ค่าคีย์จริงจะไม่ปรากฏในไฟล์ ซึ่งเป็นเรื่องสำคัญเพราะ config.yaml คือไฟล์ที่คุณต้อง commit ลงในระบบควบคุมเวอร์ชัน

มีสองรายการที่ใช้ชื่อ strong เหมือนกันโดยเจตนา เมื่อมี deployment มากกว่าหนึ่งรายการใช้ model_name เดียวกัน ตัว router จะถือว่ารายการเหล่านั้นสามารถใช้แทนกันได้และกระจายคำขอสำหรับชื่อนั้นไปยัง deployment ต่างๆ นี่คือวิธีที่ strong รับมือกับกรณีที่ผู้ให้บริการรายหนึ่งมีปัญหาชั่วคราว เมื่อ deployment หนึ่งเข้าสู่สถานะ cooldown (ดูรายละเอียดด้านล่าง) คำขอใหม่สำหรับ strong จะถูกส่งไปยังอีกรายการหนึ่งแทน

num_retries: 2 จะลองส่งคำขอซ้ำสำหรับข้อผิดพลาดที่สามารถลองใหม่ได้สูงสุด 2 ครั้ง การลองใหม่เหล่านี้สามารถเลือก deployment อื่นที่พร้อมใช้งานในกลุ่มโมเดลเดียวกันได้ เอกสารสถาปัตยกรรมของ LiteLLM ซึ่งตรวจสอบเมื่อ 2026-10-29 อธิบายว่าการลองใหม่ภายในกลุ่มและการทำ fallback ข้ามกลุ่มเป็นขั้นตอนที่แยกจากกัน ดังนั้นการลองใหม่สำหรับ strong จึงสามารถไปลงที่ผู้ให้บริการอีกรายได้โดยไม่ต้องเปิดใช้งาน weighted failover ส่วนการทำ fallback จะทำงานก็ต่อเมื่อใช้สิทธิ์การลองใหม่จนครบแล้วเท่านั้น

allowed_fails และ cooldown_time เป็นตัวเลือกของ router จึงต้องวางไว้ภายใต้ router_settings ตัว proxy จะสร้าง router จากส่วนนั้น และในเวอร์ชัน v1.95.0 หากเขียน cooldown_time ไว้ภายใต้ litellm_settings ค่าดังกล่าวจะไม่ถูกนำไปใช้ ทำให้ cooldown ยังคงค่าเริ่มต้นที่ 5 วินาทีอย่างเงียบๆ cooldown_time: 30 กำหนดระยะเวลาที่ deployment จะถูกนำออกจากระบบหมุนเวียนเมื่อเข้าสู่สถานะ cooldown เอกสารอ้างอิงการตั้งค่าระบุว่า allowed_fails คือจำนวนความล้มเหลวที่ deployment ต้องทำเกินภายในระยะเวลา cooldown_time ก่อนที่จะถูก cooldown ในซอร์สโค้ดของ v1.95.0 ค่า allowed_fails: 3 คือค่าเริ่มต้น ซึ่งที่ค่าเริ่มต้นนี้ router จะใช้เงื่อนไขทริกเกอร์ที่กำหนดไว้ภายในระบบ โดยจำนวนความล้มเหลวจะมีผลก็ต่อเมื่อคุณกำหนดค่าอื่น เงื่อนไขเหล่านี้รวมถึงการ cooldown ทันทีเมื่อได้รับ response 429 สำหรับกลุ่มที่มี deployment มากกว่าหนึ่งรายการ, ความล้มเหลวเกิน 50% ในนาทีปัจจุบันหลังจากมีการส่งคำขอไปแล้วอย่างน้อย 5 ครั้งสำหรับกลุ่มดังกล่าว และข้อผิดพลาดที่ router จะไม่ลองใหม่ เช่น 401 จากคีย์ที่ไม่ถูกต้อง นอกจากนี้ยังมีทริกเกอร์แยกต่างหากที่จะ cooldown deployment เดียวเมื่อคำขอทั้งหมดในนาทีปัจจุบันล้มเหลวและปริมาณการใช้งานถึง SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD ซึ่งมีค่าเริ่มต้นที่ 1000 คำขอ ดังนั้นสำหรับ strong ซึ่งมี deployment สองรายการ หากผู้ให้บริการส่งค่า 500 กลับมาเป็นชุด ระบบจะหยุดส่งคำขอไปยังรายการนั้นทันที ในขณะที่ข้อผิดพลาด 500 ที่เกิดขึ้นประปรายทุกสองสามนาทีจะไม่ทำให้เกิดการ cooldown ส่วน bulk มี deployment เพียงรายการเดียว ทริกเกอร์อัตราความล้มเหลวจึงไม่มีผลกับรายการนี้ การเกิดข้อผิดพลาด 500 เป็นชุดที่ยังไม่ถึง 1000 คำขอต่อนาทีจะทำให้มันยังคงอยู่ในระบบหมุนเวียน และสิ่งที่ปกป้องผู้เรียกใช้งานคือ num_retries ตามด้วยการทำ fallback ไปยัง strong

fallbacks และ context_window_fallbacks มีทริกเกอร์ที่แตกต่างกัน และแบบที่สองคือสิ่งที่ผู้ใช้มักมองข้ามแต่มีประโยชน์มาก

  • fallbacks จะทำงานเมื่อการเรียกใช้งานหลักล้มเหลว
  • context_window_fallbacks จะทำงานเมื่อผู้ให้บริการปฏิเสธคำขอเนื่องจากมีความยาวเกิน context window ของโมเดลนั้น ดังนั้น prompt ที่มีขนาดใหญ่เกินไปจะถูกส่งไปยังโมเดลที่มีพื้นที่เพียงพอแทนที่จะส่งข้อผิดพลาดกลับไปยังผู้เรียก

นอกจากนี้ยังมี content_policy_fallbacks สำหรับกรณีที่ผู้ให้บริการปฏิเสธเนื่องจากนโยบายเนื้อหา ให้ตั้งค่านี้เฉพาะเมื่อคุณมีปลายทางที่เหมาะสมสำหรับส่งคำขอเหล่านั้นไปเท่านั้น

การติดตั้ง LiteLLM บน VPS ด้วย Docker Compose

สร้างไดเรกทอรีสำหรับเก็บไฟล์สามไฟล์ ได้แก่ config.yaml, docker-compose.yml และ .env คู่มือเริ่มต้นใช้งานฉบับย่อของผู้พัฒนาแนะนำให้ดึงแท็ก latest มาใช้ แต่ขอแนะนำให้ระบุเวอร์ชัน (pin) ของแท็กแทน เพื่อให้การอัปเกรดเกิดขึ้นเฉพาะเมื่อคุณแก้ไขไฟล์เท่านั้น และทำให้การย้อนกลับ (rollback) ทำได้เพียงแก้ไขบรรทัดเดียว แท็กเพียงอย่างเดียวไม่สามารถรับประกันเนื้อหาที่เหมือนเดิมได้ เนื่องจากแท็กของอิมเมจสามารถเปลี่ยนแปลงได้ และผู้เผยแพร่สามารถชี้แท็กเดิมไปยังอิมเมจใหม่ได้ หากคุณต้องการให้ docker compose up -d ในเดือนหน้ายังคงเป็นเกตเวย์ตัวเดิมที่คุณได้รับในวันนี้ ให้ระบุ image digest ต่อท้ายในรูปแบบ ghcr.io/berriai/litellm:v1.95.0@sha256:<digest> โดยสามารถใช้คำสั่ง docker buildx imagetools inspect ghcr.io/berriai/litellm:v1.95.0 เพื่อดูค่าดังกล่าว

services:
  litellm:
    image: ghcr.io/berriai/litellm:v1.95.0
    restart: unless-stopped
    command: ["--config", "/app/config.yaml", "--num_workers", "1"]
    ports:
      - "127.0.0.1:4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    env_file: .env
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: litellm
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

ในที่นี้ Compose จะอ่านไฟล์ .env สองครั้ง ครั้งแรกเพื่อแทนที่ค่า ${POSTGRES_PASSWORD} ภายในไฟล์ compose เอง และครั้งที่สองผ่านทาง env_file เพื่อส่งผ่านตัวแปรทั้งหมดเข้าไปในคอนเทนเนอร์

v1.95.0 คือเวอร์ชันล่าสุด ณ เดือนสิงหาคม 2026 โปรดตรวจสอบหน้า releases ของโปรเจกต์และระบุเวอร์ชันที่เป็นปัจจุบันในขณะที่คุณติดตั้ง แต่ละเวอร์ชันที่เผยแพร่จะมีลายเซ็นกำกับไว้ คุณจึงสามารถตรวจสอบอิมเมจก่อนที่จะเชื่อถือได้:

cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0

บรรทัดกำหนดพอร์ตคือ 127.0.0.1:4000:4000 ซึ่งเป็นการเปิดพอร์ตบนอินเทอร์เฟซ loopback เท่านั้น หากคุณเขียนเป็น 4000:4000 เกตเวย์ของคุณจะสามารถเข้าถึงได้จากอินเทอร์เน็ตทั้งหมด เนื่องจาก Docker จะเพิ่มกฎของตนเองลงใน iptables ใน chain FORWARD ซึ่งจะถูกประเมินก่อนกฎของ ufw ดังนั้น ufw deny 4000 จึงไม่สามารถหยุดการเชื่อมต่อนี้ได้ นี่เป็นวิธีที่พบบ่อยที่สุดที่ทำให้เกตเวย์ที่โฮสต์เองถูกเปิดเผยต่อสาธารณะ: ดูรายละเอียดที่ วิธีที่ Docker เปิดพอร์ตคอนเทนเนอร์ข้ามการตั้งค่า ufw โดยควรให้ทราฟฟิกจากภายนอกเข้ามาผ่าน reverse proxy แทน

เก็บคีย์ของผู้ให้บริการไว้นอกอิมเมจ

ไฟล์ .env เก็บความลับทั้งหมดไว้ โดยจะถูกส่งผ่านเป็น environment variable ในขณะรันไทม์ ดังนั้นจึงไม่มีการฝังไว้ในอิมเมจและไม่มีการ commit ลงใน source control

LITELLM_MASTER_KEY=sk-REPLACE_ME
LITELLM_SALT_KEY=sk-REPLACE_ME_TOO
POSTGRES_PASSWORD=REPLACE_ME_AS_WELL
DATABASE_URL=postgresql://litellm:REPLACE_ME_AS_WELL@db:5432/litellm
STORE_MODEL_IN_DB=True
LITELLM_MODE=PRODUCTION
LITELLM_LOG=ERROR
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...

สร้างคีย์ LiteLLM สองชุดด้วยค่าสุ่มที่แท้จริง จากนั้นจำกัดสิทธิ์การเข้าถึงไฟล์:

printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .env

LITELLM_MASTER_KEY คือข้อมูลประจำตัวของผู้ดูแลระบบ ใช้สำหรับยืนยันตัวตนกับ management API และเป็นรหัสผ่านสำหรับ Admin UI ที่ /ui ห้ามไม่ให้แอปพลิเคชันใดๆ ถือครองคีย์นี้ไว้

LITELLM_SALT_KEY ใช้สำหรับเข้ารหัสข้อมูลประจำตัวของผู้ให้บริการที่จัดเก็บอยู่ในฐานข้อมูล ให้ตั้งค่าเพียงครั้งเดียวแล้วไม่ต้องแก้ไขอีก หากเปลี่ยนในภายหลัง ข้อมูลประจำตัวที่จัดเก็บไว้เดิมจะไม่สามารถถอดรหัสได้ ส่งผลให้ gateway เริ่มทำงานได้ตามปกติ แต่การเรียกใช้งานผู้ให้บริการเหล่านั้นทั้งหมดจะล้มเหลวเนื่องจากปัญหาการยืนยันตัวตน

STORE_MODEL_IN_DB=True ช่วยให้คุณเพิ่มและแก้ไขโมเดลผ่าน Admin UI ได้โดยไม่ต้องแก้ไขไฟล์ config.yaml แม้จะสะดวก แต่ก็ทำให้แหล่งข้อมูลหลัก (source of truth) ถูกแยกออกเป็นสองส่วน ให้ตัดสินใจว่าแหล่งข้อมูลใดจะเป็นหลักและบันทึกการตัดสินใจนั้นไว้ข้างไฟล์ config

เหตุผลที่ต้องเก็บคีย์ไว้นอกไฟล์ config เป็นเหตุผลเดียวกับที่ต้องเก็บคีย์ไว้นอกเครื่องมือที่คุณมอบให้กับ AI agent เนื้อหา การเก็บความลับของผู้ให้บริการไว้นอก AI agents อธิบายถึงรูปแบบดังกล่าว และ ไฟล์ env และความลับใน Docker Compose อธิบายถึงวิธีการดำเนินการ

เริ่มการทำงานและตรวจสอบการบูตครั้งแรก:

docker compose up -d
docker compose logs -f litellm

ตรวจสอบว่าระบบทำงานได้จริง

มีการตรวจสอบแบบไม่ระบุตัวตนสองรายการและการตรวจสอบแบบระบุตัวตนหนึ่งรายการ ซึ่งทั้งหมดล้มเหลวด้วยสาเหตุที่แตกต่างกัน

curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readiness

/health/liveliness ไม่จำเป็นต้องมีการยืนยันตัวตนและจะตอบกลับเป็น "I'm alive!" ในขณะที่กระบวนการทำงานอยู่ ส่วน /health/readiness ก็ไม่จำเป็นต้องมีการยืนยันตัวตนเช่นกัน โดยจะส่งคืนออบเจกต์ JSON ที่มีฟิลด์ "status": "healthy" และ db หรือส่งคืนสถานะ 503 เมื่อไม่สามารถเข้าถึงฐานข้อมูลได้ ให้ชี้ระบบตรวจสอบของคุณไปที่ readiness เนื่องจาก liveliness จะแสดงสถานะเป็นสีเขียวเสมอในเกตเวย์ที่ไม่สามารถค้นหา virtual key ได้

การตรวจสอบแบบระบุตัวตนคือส่วนที่สื่อสารกับผู้ให้บริการ:

curl -s http://127.0.0.1:4000/health \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

ระบบจะตอบกลับด้วยอาร์เรย์ healthy_endpoints และ unhealthy_endpoints หากโมเดลที่อยู่ใน unhealthy_endpoints แสดงข้อผิดพลาดด้านการยืนยันตัวตน หมายความว่าคีย์ของผู้ให้บริการใน .env ไม่ถูกต้องหรือหายไป ซึ่งเป็นความล้มเหลวที่คุณต้องการตรวจพบในขณะนี้ เนื่องจากมีการตั้งค่า background_health_checks: true ไว้ พร็อกซีจะเรียกใช้การตรวจสอบเหล่านี้ทุกๆ health_check_interval วินาทีด้วยตัวเอง และ /health จะส่งคืนผลลัพธ์ล่าสุด ดังนั้นการ polling จึงไม่เป็นการส่งคำขอทดสอบไปยังผู้ให้บริการของคุณในทุกครั้งที่เรียกใช้

คีย์เสมือนและงบประมาณแยกตามคีย์

แต่ละแอปพลิเคชันจะได้รับคีย์ของตนเอง ซึ่งสร้างโดยอ้างอิงจาก master key

curl -s http://127.0.0.1:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "key_alias": "nightly-summariser",
    "models": ["bulk"],
    "max_budget": 5,
    "budget_duration": "30d",
    "rpm_limit": 60,
    "tpm_limit": 200000
  }'

การตอบกลับมีฟิลด์ key ที่ขึ้นต้นด้วย sk- สตริงดังกล่าวคือสิ่งที่แอปพลิเคชันได้รับ และเป็นข้อมูลเพียงอย่างเดียวที่แอปพลิเคชันจะได้รับ

  • models คือรายการอนุญาตว่าคีย์นี้สามารถส่งคำขออะไรได้บ้าง คีย์ข้างต้นสามารถขอได้เฉพาะ bulk เท่านั้น
  • max_budget: 5 ที่กำหนดด้วย budget_duration: "30d" มีค่า 5 ดอลลาร์สหรัฐต่อเดือนปฏิทิน LiteLLM จะรีเซ็ตงบประมาณ 30d ในวันที่ 1 ของทุกเดือนเวลาเที่ยงคืน โดยใช้ UTC เว้นแต่คุณจะกำหนด timezone ไว้ภายใต้ litellm_settings งบประมาณนี้ไม่ใช่รอบ 30 วันแบบเลื่อน ดังนั้นเมื่อคีย์ใช้เงินครบ 5 ดอลลาร์แล้ว คีย์จะใช้งานไม่ได้จนกว่าจะถึงวันที่ 1 ถัดไป
  • rpm_limit และ tpm_limit จำกัดจำนวนคำขอต่อนาทีและจำนวน token ต่อนาทีสำหรับคีย์นี้เท่านั้น
  • key_alias คือชื่อที่คุณจะใช้ระบุคีย์นี้ใน spend log เมื่อเวลาผ่านไป 6 สัปดาห์ ควรกำหนดค่านี้เสมอ

เมื่องบประมาณหมด การเรียกจะล้มเหลวด้วย error ประเภท budget_exceeded และมีข้อความในรูปแบบนี้:

Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>

status code ขึ้นอยู่กับ release ที่ใช้ ใน v1.95.0 ซึ่งถูก pin ไว้ ค่าเป็น HTTP 429 ตั้งแต่ v1.104.0 ค่าเริ่มต้นคือ HTTP 422 และการตั้งค่า budget_exceeded_status_code: 429 ภายใต้ litellm_settings จะทำให้กลับไปใช้ code เดิม การที่ rpm_limit และ tpm_limit ถึงขีดจำกัดจริงยังคงส่งคืน 429 ในทั้งสอง release ตรวจสอบว่าคุณได้รับ code ใดหลังการ upgrade ทุกครั้ง

status code เป็นสาเหตุที่ทำให้เรื่องนี้สับสน เพราะไม่มี code ใดระบุคำว่า "budget" ไลบรารี client จะรายงาน 429 ว่าเป็น rate limit และอาจ retry ด้วย backoff ทั้งที่ budget จะไม่กลับมาใช้ได้จนกว่าจะถึงเวลา reset ส่วน 422 จะถูกรายงานว่าเป็นคำขอที่ไม่สามารถประมวลผลได้ ให้บันทึก response body ไว้ถัดจาก status code มิฉะนั้นการใช้งบประมาณจนหมดจะดูเหมือนปัญหาอื่นทุกครั้ง

ตรวจสอบและปรับคีย์ผ่าน management API เดียวกัน:

curl -s "http://127.0.0.1:4000/key/info?key=sk-..." \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

curl -s -X POST http://127.0.0.1:4000/key/update \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"key": "sk-...", "max_budget": 25}'

งบประมาณที่บังคับใช้ที่ gateway ยังคงมีผลแม้สาเหตุที่ผิดพลาดจะอยู่ที่ agent เอง นี่จึงเป็นกลไกหลักของ การควบคุมค่าใช้จ่ายสำหรับ AI agent บน VPS

การส่งงานจำนวนมากไปยังโมเดลราคาประหยัด

กำหนดให้ไคลเอนต์ชี้ไปยังเกตเวย์ โดยระบุ Base URL, คีย์ และชื่อโมเดล:

curl -s http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-<the virtual key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "bulk",
    "messages": [{"role": "user", "content": "Say hello in five words."}]
  }'

ไลบรารีไคลเอนต์ของ OpenAI ทุกตัวทำงานในลักษณะเดียวกัน แม้ว่าชื่อตัวเลือกจะแตกต่างกันไปตามภาษา สำหรับไคลเอนต์ Python ให้ตั้งค่า base_url เป็น https://gateway.example.com/v1 และ api_key เป็นคีย์เสมือน ส่วนไคลเอนต์ JavaScript และ TypeScript จะเรียกใช้ตัวเลือกทั้งสองนี้ว่า baseURL และ apiKey

นโยบายการกำหนดเส้นทางจาก config.yaml จะถูกนำมาใช้โดยที่ผู้เรียกใช้งานไม่จำเป็นต้องทราบ คำขอสำหรับ bulk จะถูกส่งไปยังโมเดลราคาประหยัด หากการเรียกนั้นล้มเหลวหลังจากพยายามซ้ำแล้ว คำขอจะถูกส่งซ้ำไปยัง strong หากพรอมต์มีความยาวเกินกว่าที่ bulk จะรองรับ context_window_fallbacks จะส่งคำขอนั้นไปยัง strong แทนที่จะส่งคืนข้อผิดพลาด งานจำนวนมาก เช่น การจำแนกประเภทหรือการสรุปข้อมูลค้าง จะทำงานด้วยต้นทุนที่ต่ำโดยค่าเริ่มต้น และจะมีเพียงคำขอที่ซับซ้อนเท่านั้นที่ทำให้เกิดค่าใช้จ่ายสูงขึ้น

นี่คือจุดที่เกตเวย์แสดงความคุ้มค่าสำหรับเอเจนต์ที่ใช้เครื่องมือ โดยทั้ง เซิร์ฟเวอร์ MCP (model context protocol) บน VPS เดียวกัน และเอเจนต์ที่ควบคุมเซิร์ฟเวอร์นั้น สามารถชี้ไปยัง endpoint เดียวกันได้ ทำให้สามารถเปลี่ยนโมเดลที่อยู่เบื้องหลังได้โดยไม่ต้องปรับใช้ (redeploy) บริการใดบริการหนึ่งใหม่

จะทราบได้อย่างไรว่ามีการใช้ fallback

นี่คือกรณีที่ทำให้เกิดค่าใช้จ่ายโดยตรวจพบได้ยาก เพราะทุกอย่างดูเหมือนทำงานปกติ การใช้ fallback ที่สำเร็จจะส่ง HTTP 200 พร้อม response body ทั่วไป โมเดลราคาถูกอาจหยุดทำงานเป็นเวลาหนึ่งวัน โดยทุกคำขอถูกส่งไปยังโมเดลราคาแพงอย่างเงียบ ๆ และหลักฐานแรกที่พบอาจเป็นใบแจ้งค่าใช้บริการ

มีหลักฐานอยู่ใน response headers ให้ขอข้อมูลเหล่านี้:

curl -s -D - -o /dev/null http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-<the virtual key>" \
  -H 'Content-Type: application/json' \
  -d '{"model":"bulk","messages":[{"role":"user","content":"ping"}]}' \
  | grep -i '^x-litellm'
  • x-litellm-model-group คือชื่อโมเดลที่ใช้ route คำขอ เช่น bulk ส่วน x-litellm-model-id คือ ID ของ deployment ที่ตอบคำขอ ซึ่งค้นหาได้ด้วย /v1/model/info?litellm_model_id=... หาก ID ดังกล่าวไม่ใช่หนึ่งใน deployment ของ bulk แสดงว่ามีการใช้ fallback
  • x-litellm-attempted-fallbacks และ x-litellm-attempted-retries ใช้นับจำนวนเหตุการณ์เหล่านี้ ในคำขอที่ทำงานปกติ ทั้งสองค่าจะไม่แสดงจำนวนที่มากกว่า 0
  • x-litellm-response-cost คือต้นทุนของคำขอนั้นในหน่วยดอลลาร์สหรัฐ
  • x-litellm-call-id คือ identifier ที่ใช้ค้นหาคำขอเดียวกันใน log

บันทึก x-litellm-attempted-fallbacks ในทุกคำขอ และตั้ง alert เมื่อค่ามากกว่า 0 ตัวเลขนี้เป็นตัวแยกระหว่าง routing policy ที่ทำงานถูกต้องกับ routing policy ที่เปลี่ยนเป็น “ใช้โมเดลราคาแพงเสมอ” โดยไม่มีใครสังเกต

การติดตามแบบเต็มรูปแบบเรียกว่า tracing และควรตั้งค่าแยกต่างหาก: การ self-hosted Langfuse สำหรับ tracing การเรียก agent LiteLLM มี callback ให้ใช้งาน การเชื่อมต่อจึงใช้เพียง 2 บรรทัดและ credentials

litellm_settings:
  success_callback: ["langfuse"]
  failure_callback: ["langfuse"]
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.com

สำหรับ Langfuse v3 และรุ่นถัดไป หน้า Langfuse ของ LiteLLM แนะนำ preset langfuse_otel ในปัจจุบัน แต่ callback langfuse ข้างต้นยังมีเอกสารรองรับ ให้ตั้งค่า failure_callback และ success_callback ด้วย หากข้ามขั้นตอนนี้ trace ที่จัดเก็บไว้จะมีเฉพาะคำขอที่ไม่มีสิ่งใดผิดพลาดเท่านั้น นอกเหนือจากส่วนนี้ LiteLLM จะเขียน spend row สำหรับทุกคำขอลงใน Postgres และ Admin UI ที่ /ui จะอ่านข้อมูลจากตารางดังกล่าว ตารางนี้จะขยายตามปริมาณ traffic จึงควรตรวจสอบการใช้พื้นที่เมื่อ disk มีขนาดเล็ก

การวาง gateway ไว้หลัง reverse proxy

ไม่มีสิ่งใดจากภายนอกควรเข้าถึงพอร์ต 4000 ได้โดยตรง ให้ทำ TLS termination ที่ nginx หรือ Caddy แล้วส่งต่อคำขอไปยัง loopback address

location / {
    proxy_pass http://127.0.0.1:4000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 600s;
}

มีสองบรรทัดที่ผู้คนมักลืมใส่ไว้ proxy_buffering off มีความสำคัญเนื่องจากการทำ streaming completion คือชุดของ server-sent events หากเปิดใช้งาน buffering ไว้ nginx จะรวบรวมข้อมูลเป็นส่วนๆ ในบัฟเฟอร์ก่อนส่งต่อ ทำให้การแสดงผลที่ฝั่งไคลเอนต์ล่าช้า proxy_read_timeout 600s มีความสำคัญเนื่องจากค่าเริ่มต้น 60 วินาทีของ nginx คือระยะเวลาที่นานที่สุดที่ nginx จะรอระหว่างการอ่านข้อมูลสองครั้งจาก gateway ไม่ใช่การจำกัดเวลาของทั้ง response หากเป็น completion แบบไม่ทำ stream จะไม่มีการส่งข้อมูลใดๆ จนกว่าการประมวลผลจะเสร็จสิ้น ดังนั้นหากใช้เวลานานเกิน 60 วินาทีโดยไม่มีข้อมูลส่งมา ไคลเอนต์จะได้รับข้อผิดพลาด 504 ในขณะที่ error log จะบันทึก upstream timed out (110: Connection timed out) while reading response header from upstream เอาไว้ ส่วน completion แบบ stream ที่ส่งข้อมูลออกมาเป็นระยะสามารถทำงานได้นานกว่า 60 วินาที โดยจะติด timeout ก็ต่อเมื่อโมเดลหยุดส่งข้อมูลนานเกินระยะเวลานั้นเท่านั้น

สำหรับใบรับรอง Certbot กับ Let's Encrypt บน nginx เป็นวิธีที่รวดเร็วที่สุด หากเซิร์ฟเวอร์ให้บริการคอนเทนเนอร์หลายตัวอยู่แล้ว Traefik หน้าแอปพลิเคชัน Compose หลายตัว จะช่วยจัดการเรื่อง routing และใบรับรองไว้ในที่เดียว

เกตเวย์กลายเป็นจุดเดียวที่อาจทำให้ระบบล้มเหลว

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

  • การตั้งค่าที่ผิดพลาดจะทำให้ทุกอย่างหยุดทำงานพร้อมกัน restart: unless-stopped จะรีสตาร์ทเมื่อเกิดการแครช และมันจะรีสตาร์ทคอนเทนเนอร์ที่ไม่สามารถอ่านไฟล์ config.yaml ซ้ำไปซ้ำมา ให้อ่าน docker compose logs litellm หลังจากแก้ไขการตั้งค่าทุกครั้ง และทำการเปลี่ยนแปลงการตั้งค่าเมื่อคุณมีเวลาตรวจสอบผลลัพธ์
  • Postgres อยู่ในเส้นทางการร้องขอเมื่อเกิด cache miss การค้นหา Virtual key จะใช้ฐานข้อมูลเมื่อคีย์ไม่ได้อยู่ในแคช ส่วนการบันทึกค่าใช้จ่ายจะทำงานแบบอะซิงโครนัสหลังจากได้รับคำตอบแล้ว การที่ /health/readiness ส่งค่า 503 กลับมาคือคำเตือนว่าเกตเวย์ยังทำงานอยู่แต่ไม่สามารถทำทั้งสองอย่างนั้นได้
  • ใช้จำนวนคอร์ให้เต็มที่ก่อน แล้วค่อยเพิ่มอินสแตนซ์ คำแนะนำสำหรับการใช้งานจริงของโปรเจกต์ที่ให้ใช้ worker หนึ่งตัวต่อหนึ่งอินสแตนซ์ (--num_workers 1) นั้นมีไว้สำหรับ Kubernetes หรือระบบ autoscaler อื่นๆ ที่เพิ่มอินสแตนซ์ให้คุณ สำหรับ VM เครื่องเดียวหรือคอนเทนเนอร์เดี่ยวแบบนี้ คำแนะนำคือตรงกันข้าม: ให้ตั้งค่าจำนวน worker เท่ากับจำนวน vCPU ของเครื่อง บนเครื่องที่มี 1 vCPU ตามที่กล่าวข้างต้น ค่านี้คือ --num_workers 1 หากใช้เครื่องที่ใหญ่ขึ้นให้เพิ่มจำนวนขึ้น และต้องจำไว้ว่า worker แต่ละตัวใช้หน่วยความจำของตัวเอง การเพิ่มเกตเวย์ตัวที่สองไว้หลัง load balancer จะช่วยลดปัญหาการพึ่งพาคอนเทนเนอร์เดียว แต่ไม่ได้ช่วยลดการพึ่งพาฐานข้อมูล
  • สำรองข้อมูลที่คุณไม่สามารถสร้างใหม่ได้ นั่นคือ config.yaml และ .env รวมไปถึง pg_dump ของฐานข้อมูล การสูญเสีย LITELLM_SALT_KEY จะทำให้ข้อมูลรับรองของผู้ให้บริการที่เข้ารหัสไว้ภายในไฟล์ดัมพ์นั้นใช้งานไม่ได้ ดังนั้นไฟล์ env และไฟล์ดัมพ์จึงควรอยู่ในงานสำรองข้อมูลเดียวกัน: การสำรองข้อมูลด้วย restic ไปยังที่จัดเก็บภายนอก

การอัปเกรดทำได้โดยการแก้ไข image tag แล้วรัน docker compose up -d โดยปกติ LiteLLM จะรัน prisma migrate deploy เมื่อเริ่มต้นระบบ ดังนั้นคอนเทนเนอร์ใหม่จะทำการย้าย schema ฐานข้อมูลในการบูตครั้งแรก ให้ทำไฟล์ดัมพ์ก่อนที่คุณจะเปลี่ยน tag เพราะการนำอิมเมจเก่ากลับมาใช้ไม่สามารถย้อนการย้าย schema ที่รันไปแล้วได้

ให้อ่านบันทึกประจำรุ่น (release notes) ของทุกเวอร์ชันที่คุณข้าม ไม่ใช่แค่อ่านเฉพาะเวอร์ชันที่คุณจะอัปเกรดไปถึง การย้ายจาก v1.95.0 ไปยัง v1.104.0 หรือใหม่กว่านั้นเกี่ยวข้องกับการเปลี่ยนแปลงที่อาจทำให้ระบบเดิมใช้งานไม่ได้หลายประการ เช่น รหัสสถานะงบประมาณที่กล่าวถึงข้างต้น, พร็อกซีที่ปฏิเสธการเริ่มทำงานหากไม่มีการตั้งค่า master key, ตั้งค่าเป็นค่าว่าง หรือใช้ master key ที่เป็นที่รู้จักกันทั่วไป และพร็อกซีที่จะหยุดทำงานเมื่อการตั้งค่าฐานข้อมูลล้มเหลวในระหว่างเริ่มระบบ ซึ่งภายใต้ restart: unless-stopped จะแสดงผลเป็นวงจรการรีสตาร์ท หากคุณอัปเกรดมาจาก v1.102.x หรือเก่ากว่า บันทึกของ v1.104.0 ยังขอให้คุณสร้าง LiteLLM_SpendLogs indexes สองรายการด้วยตัวเองอีกด้วย

FAQ

LiteLLM เพิ่ม latency ที่สังเกตได้ให้กับทุกการเรียกใช้งานหรือไม่?

โปรเจกต์นี้ระบุค่า latency ไว้ที่ 8 ms ณ เปอร์เซ็นไทล์ที่ 95 ที่อัตรา 1000 คำขอต่อวินาที ตามที่ระบุไว้ใน README เมื่อเดือนพฤศจิกายน 2026 ให้ถือว่าตัวเลขนี้เป็นค่าจากผู้ผลิต ตัวเลขที่จะส่งผลต่อ latency ของคุณจริงๆ คือระยะห่างทางเครือข่ายระหว่างแอปพลิเคชันของคุณกับเกตเวย์ เนื่องจากคุณได้เพิ่มการรับส่งข้อมูลไป-กลับ (round trip) เข้าไปในทุกการเรียกใช้งาน ให้รันเกตเวย์ในภูมิภาคเดียวกับแอปพลิเคชันที่เรียกใช้งาน จากนั้นวัดค่า overhead ของคุณเองด้วย header x-litellm-overhead-duration-ms จากการตอบสนองจริง

ทำไมการสตรีมถึงหยุดทำงานหลังจากวาง nginx ไว้ด้านหน้า?

เนื่องจาก nginx จะบัฟเฟอร์การตอบสนองจาก upstream โดยค่าเริ่มต้น และการทำ completion แบบสตรีมมิ่งคือชุดของ server-sent events เมื่อเปิด proxy_buffering ไว้ nginx จะรวบรวมข้อมูลเป็นส่วนๆ ไว้ในบัฟเฟอร์ก่อนจะส่งต่อ ทำให้การส่งข้อมูลไปยังไคลเอนต์ล่าช้า ให้ตั้งค่า proxy_buffering off; ในบล็อก location และเพิ่มค่า proxy_read_timeout ในบล็อกเดียวกันด้วย โดยปกติแล้ว nginx จะตัดการเชื่อมต่อหลังจากผ่านไป 60 วินาทีหากไม่มีข้อมูลจากเกตเวย์ ซึ่งการสร้างข้อความแบบไม่สตรีมที่ใช้เวลานานมักจะถึงขีดจำกัดนี้ และไคลเอนต์จะได้รับข้อผิดพลาด 504

จะเกิดอะไรขึ้นเมื่อ virtual key ใช้งานงบประมาณจนหมด?

การเรียกใช้งานจะล้มเหลวพร้อมข้อผิดพลาดประเภท budget_exceeded และข้อความในรูปแบบ Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget> ในเวอร์ชัน v1.95.0 ที่ระบุไว้ สถานะจะเป็น HTTP 429 ส่วนตั้งแต่ v1.104.0 เป็นต้นไป ค่าเริ่มต้นจะเปลี่ยนเป็น HTTP 422 แทน ซึ่งรหัสทั้งสองไม่ได้ระบุว่าเป็นเรื่องงบประมาณ นี่คือจุดที่ทำให้เข้าใจผิด: ไลบรารีของไคลเอนต์จะรายงาน 429 ว่าเป็น rate limit และอาจพยายามเรียกซ้ำ ทำให้ผู้ใช้มัวแต่ไปไล่แก้ปัญหาเรื่องการจำกัดอัตราการใช้งานแทนที่จะอ่านข้อความแจ้งเตือน ให้บันทึก response body ควบคู่ไปกับรหัสสถานะ ตรวจสอบสถานะจริงของคีย์ด้วย /key/info?key=sk-... เทียบกับ master key และเพิ่มเพดานงบประมาณด้วย /key/update หากตั้งงบประมาณไว้ต่ำเกินไป

เกตเวย์สามารถกำหนดเส้นทางไปยังโมเดลในเครื่องได้เช่นเดียวกับโมเดลที่โฮสต์ไว้หรือไม่?

ได้ และนั่นเป็นอีกหนึ่งรายการใน model_list ให้ใช้ prefix ollama_chat/ ร่วมกับ api_base ตัวอย่างเช่น model: ollama_chat/llama3.1 ควบคู่ไปกับ api_base: http://ollama:11434 ในการตั้งค่าเครือข่ายเริ่มต้นของ Compose นั้น localhost ภายในคอนเทนเนอร์จะหมายถึงตัวคอนเทนเนอร์นั้นเอง ดังนั้นให้ใช้ชื่อบริการของ Compose หรือที่อยู่ของโฮสต์บนเครือข่าย Docker ห้ามใช้ 127.0.0.1 ยกเว้นกรณีการใช้ host networking ซึ่งคอนเทนเนอร์จะใช้ stack เครือข่ายร่วมกับโฮสต์ การติดตั้งโมเดลในเครื่องเป็นงานแยกต่างหาก: ดูที่ การโฮสต์ LLM ด้วยตัวเองโดยใช้ Ollama บน VPS

บทความนี้มีประโยชน์หรือไม่