ประเด็นสำคัญ
- ตรวจสอบเอนด์พอยต์ด้วย curl ก่อนใช้งาน OpenCode เพื่อระบุให้ชัดเจนว่าความล้มเหลวเกิดจากการตั้งค่าหรือจาก API
- ผู้ให้บริการแบบกำหนดเองต้องมีสามสิ่ง: base URL, คีย์ API และ model ID ซึ่งในที่นี้คือ uncensored
- ตั้งค่าขีดจำกัดบริบทเป็น 100,000 โทเคน เพื่อให้ตัวแทนวางแผนโดยอ้างอิงจากหน้าต่างบริบทจริง
- รองรับการสตรีมและการเรียกใช้เครื่องมือ ซึ่งเป็นสิ่งที่ลูปของตัวแทนจำเป็นต้องใช้
สิ่งที่คุณต้องมีก่อนเริ่ม
OpenCode เป็น coding agent แบบ open-source ที่ทำงานใน terminal ของคุณ สามารถเชื่อมต่อกับผู้ให้บริการโมเดลได้หลายราย และอนุญาตให้คุณเพิ่มผู้ให้บริการเองได้ หาก endpoint รองรับรูปแบบ chat ของ OpenAI API นี้รองรับรูปแบบดังกล่าว ดังนั้นการติดตั้งจึงเป็นเพียงการกรอกข้อมูลในช่องไม่กี่ช่อง
รวบรวมค่าสามค่านี้ก่อน:
- Base URL:
https://api.kimicode.top/v1 - รหัสโมเดล:
uncensored - API key: สร้างคีย์ที่ หน้า API key บัญชีใหม่สามารถรับเครดิตทดลองใช้ $0.50 ได้เพียงคลิกเดียว ซึ่งเพียงพอสำหรับการทดสอบด้านล่าง คีย์ทดลองอนุญาตให้ทำคำขอพร้อมกัน 2 คำขอและ 60 คำขอต่อนาที
เก็บคีย์ไว้ในตัวแปรสภาพแวดล้อมแทนการวางลงในไฟล์ที่คุณจะ commit:
export KIMICODE_API_KEY="your-key-here"ขั้นตอนที่ 1: ทดสอบ endpoint ด้วย curl
ทำขั้นตอนนี้ก่อนกำหนดค่าเครื่องมือใดๆ หาก curl ทำงานได้แต่ OpenCode ไม่ทำงาน แสดงว่าปัญหาอยู่ที่การตั้งค่า หาก curl ล้มเหลว คุณแก้ไขคีย์หรือ URL เพียงครั้งเดียว ไม่ใช่แก้ไขสองที่
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "Say hello in five words."}],
"max_tokens": 40
}'คุณควรได้รับออบเจกต์ JSON ที่มีอาร์เรย์ choices และบล็อก usage รหัส 401 หมายถึงคีย์ผิดหรือขาดพรีฟิกซ์ Bearer รหัส 404 มักหมายถึง URL พิมพ์ผิดหรือมี /chat/completions อยู่แล้ว
coding agent จะส่งคำตอบแบบ streaming และเรียกใช้เครื่องมือ ดังนั้นควรตรวจสอบสองส่วนนี้ด้วย:
curl -N https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"stream": true,
"messages": [{"role": "user", "content": "Count from one to five."}]
}'คุณควรเห็นบรรทัด data: หลายบรรทัด แต่ละบรรทัดมีค่าเปลี่ยนแปลง (delta) JSON เล็กๆ และลงท้ายด้วยตัวเลขการใช้งานและตัวระบุสุดท้าย ปุ่ม -N จะปิดการบัฟเฟอร์ของ curl เพื่อให้ชิ้นข้อมูลปรากฏทันทีที่ได้รับ
ขั้นตอนที่ 2: เพิ่มผู้ให้บริการที่กำหนดเองใน OpenCode
OpenCode อ่านไฟล์ config JSON opencode.json จากโฟลเดอร์โปรเจกต์หรือจาก global config directory ของมัน โดยประกาศ custom OpenAI-style providers ด้วยแพ็กเกจ OpenAI compatible ของ AI SDK, base URL และรายการโมเดล โครงสร้างด้านล่างอ้างอิงตามเอกสารสาธารณะของ OpenCode ณ เวลาที่เขียน ชื่อฟิลด์อาจเปลี่ยนแปลงระหว่างเวอร์ชัน ดังนั้นให้เปรียบเทียบกับ provider section ในเอกสาร OpenCode เวอร์ชันล่าสุดหากมีการปฏิเสธ
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"kimicode": {
"npm": "@ai-sdk/openai-compatible",
"name": "Kimicode API",
"options": {
"baseURL": "https://api.kimicode.top/v1",
"apiKey": "{env:KIMICODE_API_KEY}"
},
"models": {
"uncensored": {
"name": "Uncensored",
"limit": {
"context": 100000,
"output": 8192
}
}
}
}
},
"model": "kimicode/uncensored"
}คีย์ภายใต้ models คือ model ID ที่ส่งไปยังเซิร์ฟเวอร์อย่างแม่นยำ ดังนั้นต้องเขียนว่า uncensored บรรทัดสุดท้ายเลือก provider และโมเดลเป็นค่าเริ่มต้น โดยเขียนเป็นชื่อ provider, เครื่องหมายทับ แล้วตามด้วย model ID
รูปแบบ {env:KIMICODE_API_KEY} บอกให้ OpenCode อ่านตัวแปรจาก shell ของคุณ หากเวอร์ชันของคุณจัดการข้อมูลรับรองผ่าน login command ของมันเอง ให้ใช้วิธีนั้นและทิ้งคีย์ออกจากไฟล์ ไม่ว่าทางใดก็ตาม อย่า commit คีย์จริง
ค่ากำหนดโปรเจกต์หรือค่ากำหนดระดับระบบ
คุณสามารถเก็บบล็อกผู้ให้บริการในสองที่ ไฟล์ในโฟลเดอร์ root ของโปรเจกต์จะใช้กับ repository นั้นๆ ซึ่งเหมาะสำหรับทีมที่แชร์การตั้งค่าเดียวกัน ไฟล์ในไดเรกทอรี config ของผู้ใช้ของคุณจะใช้ในทุกที่ ซึ่งเหมาะสำหรับค่าเริ่มต้นส่วนบุคคล เมื่อมีทั้งสองที่ ไฟล์โปรเจกต์จะเพิ่มหรือแทนที่ค่าจากไฟล์ global
แนะนำให้ใช้ไฟล์ global สำหรับการกำหนดค่าผู้ให้บริการ และใช้ตัวแปรสภาพแวดล้อมสำหรับคีย์ จากนั้นทุก repository สามารถใช้ endpoint ได้ และไม่มีข้อมูลลับอยู่ข้างๆ โค้ดแหล่งของคุณ หากมีหลายคนทำงานในโปรเจกต์เดียวกัน ให้ commit เฉพาะบล็อกผู้ให้บริการโดยไม่มีคีย์ และให้แต่ละคนตั้งค่าตัวแปรของตัวเอง วิธีนี้ยังทำให้การหมุนเวียนคีย์ทำได้ง่าย: เปลี่ยนตัวแปร รีสตาร์ท terminal และไฟล์ config จะไม่เปลี่ยนแปลง
ขั้นตอนที่ 3: เลือกโมเดลและรันงาน
เริ่ม OpenCode ในโฟลเดอร์โปรเจกต์และเปิดตัวเลือกโมเดลของคุณ ผู้ให้บริการแบบกำหนดเองควรปรากฏในรายการพร้อมชื่อแสดงผลที่คุณตั้งค่า เลือกมันแล้วมอบงานเล็กๆ ที่ตรวจสอบได้ให้กับ agent เช่น อธิบายฟังก์ชันหรือเขียน unit test สำหรับไฟล์สั้นๆ
เริ่มใช้งานแบบจำกัดก่อนด้วยสองเหตุผล ประการแรก คุณสามารถตรวจสอบว่าการเรียกใช้ฟังก์ชันทำงานได้หรือไม่: เมื่อ OpenCode ขอให้อ่านหรือแก้ไขไฟล์ มันจะดำเนินการผ่านอินเทอร์เฟซการเรียกใช้ฟังก์ชัน ประการที่สอง เอเจนต์เขียนโค้ดส่งข้อความปริมาณมากต่อรอบ รวมถึงเนื้อหาไฟล์และประวัติการใช้งาน ทำให้เซสชันที่ยาวนานใช้โทเคนไปอย่างรวดเร็ว ส่วนถัดไปจะแสดงตัวเลขที่ชัดเจนในเรื่องนี้
หากโมเดลไม่ปรากฏ ให้ตรวจสอบว่าไฟล์เป็น JSON ที่ถูกต้อง, ไฟล์อยู่ที่ตำแหน่งที่ OpenCode มองหา config และชื่อ provider ตรงกับสิ่งที่พิมพ์ในฟิลด์ model
การทดสอบการเรียกใช้ฟังก์ชันและโหมด JSON โดยตรง
OpenCode ใช้การเรียกใช้ฟังก์ชันเพื่ออ่านไฟล์ รันคำสั่ง และแก้ไขโค้ด ดังนั้นจึงควรยืนยันว่าเอนด์พอยต์รองรับการกำหนดนิยามฟังก์ชันก่อนที่จะโทษเอเจนต์เมื่อเกิดข้อผิดพลาด คำขอนี้มีฟังก์ชันหนึ่งรายการและถามคำถามที่ต้องการฟังก์ชันดังกล่าว
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
"tools": [{
"type": "function",
"function": {
"name": "read_file",
"description": "Read a text file by path",
"parameters": {
"type": "object",
"properties": {"path": {"type": "string"}},
"required": ["path"]
}
}
}],
"tool_choice": "auto"
}'การตอบกลับที่ดีควรมี entry tool_calls ที่ระบุ read_file พร้อม string argument เป็น JSON agent จะรัน tool นั้น แล้วส่งผลลัพธ์กลับเป็น message ที่มี role ตั้งค่าเป็น tool จากนั้นโมเดลจะดำเนินการต่อจากจุดนั้น หากเห็นเพียงข้อความธรรมดา ให้ลองใช้ prompt ที่ตรงไปตรงมามากขึ้น เนื่องจากการที่โมเดลตัดสินใจเรียกใช้ tool เป็นส่วนหนึ่งของพฤติกรรม
JSON mode เป็นสวิตช์แยกต่างหาก การเพิ่ม "response_format": {"type": "json_object"} จะขอ output JSON ที่ถูกต้อง และช่วยเมื่อสคริปต์อื่นต้อง parse ข้อมูลที่ส่งกลับมา ควรกล่าวถึง JSON ใน prompt ของคุณด้วย เพื่อให้โมเดลรู้ถึงรูปแบบที่คุณคาดหวัง
ขนาดบริบทและต้นทุนของเซสชัน
context window มีขนาด 100,000 tokens โดยนับรวม prompt และ completion การตั้งค่า limit.context เป็น 100000 จะแจ้งให้ agent รู้ถึงขีดจำกัดจริง เพื่อให้สามารถตัดหรือสรุปประวัติก่อนที่เซิร์ฟเวอร์จะปฏิเสธคำขอ การ completion อาจใช้พื้นที่ที่เหลืออยู่ และ max_tokens เป็นตัวเลือก
การเรียกเก็บเงินคือ $0.15 ต่อ 1M input tokens และ $0.50 ต่อ 1M output tokens Agents ใช้ input เป็นหนัก เพราะทุก turn จะส่งการสนทนาใหม่ ตัวอย่างการคำนวณสำหรับเซสชันปานกลาง:
- 40 turns แต่ละรอบส่ง input tokens ประมาณ 30,000: input tokens รวม 1,200,000 ซึ่งคิดเป็น 1.2 x $0.15 = $0.18
- แต่ละรอบส่งค่ากลับประมาณ 800 โทเคนเอาต์พุต: 32,000 โทเคนเอาต์พุต ซึ่งคิดเป็น 0.032 x $0.50 = $0.016
- รวม: $0.196 หรือประมาณยี่สิบเซ็นต์สำหรับเซสชันทั้งหมด
ตัวเลขของคุณอาจแตกต่างกัน อ่านค่า usage ในการตอบกลับ หรือดูเฮดเดอร์ X-Balance-USD ซึ่งรายงานยอดคงเหลือที่เหลืออยู่ของคุณในการตอบกลับแต่ละครั้ง เครดิตเป็นแบบเติมเงินล่วงหน้าและไม่หมดอายุ และคำขอที่ล้มเหลวหรือถูกปฏิเสธจะไม่ถูกเรียกเก็บเงิน รายละเอียดดูได้ที่ หน้าราคา
ความคาดหวังที่ตรงไปตรงมาสำหรับเอเจนต์เขียนโค้ด
นี่คือโมเดลข้อความทั่วไปที่ปรับแต่งมาเพื่อตอบคำถามโดยไม่มีการปฏิเสธเนื้อหาสำหรับการใช้งานผู้ใหญ่ที่ถูกต้องตามกฎหมาย ไม่ใช่โมเดลที่สร้างมาเฉพาะสำหรับโค้ด และหน้านี้ไม่ได้มีการอ้างถึงผลการทดสอบใดๆ ว่ามันแก้ไขรีโพสิตอรีของคุณได้อย่างน่าเชื่อถือหรือไม่ เป็นสิ่งที่ควรทดสอบด้วยงานของคุณเอง โดยเปิดการควบคุมเวอร์ชันไว้ ก่อนที่จะมอบหมายงานสำคัญให้มัน
มันจัดการงานพื้นฐานที่ agent ต้องการ: การเรียกใช้ฟังก์ชันพร้อมสตรีม tool_calls, การส่งผลลัพธ์กลับเป็นข้อความ role: "tool" และโหมด JSON ผ่าน response_format รองรับเฉพาะข้อความ ไม่มีรูปภาพ ดังนั้นฟีเจอร์ที่แนบภาพหน้าจอจะทำงานไม่ได้
ข้อจำกัดสองอย่างสำคัญสำหรับ agent คีย์แบบเต็มอนุญาตให้ทำคำขอพร้อมกัน 8 คำขอและ 300 คำขอต่อนาที Agent ย่อยหรือการเรียกใช้ฟังก์ชันแบบขนานที่ส่งคำขอจำนวนมากพร้อมกันอาจชนกับขีดจำกัดการทำงานพร้อมกัน และคำขอแบบสตรีมจะครอบครองช่องจนกว่าสตรีมจะสิ้นสุด เมื่อเกิดเหตุการณ์นี้คุณจะได้รับ HTTP 429 พร้อม code concurrency Code rate_limited หมายถึงคำขอเกินต่อนาที ในกรณี overload ชั่วคราวคุณอาจเห็น 429 พร้อม Retry-After: 5 ลดความขนานหรือรอแล้วลองใหม่
การแก้ไขปัญหา
| อาการ | สาเหตุที่เป็นไปได้ | การแก้ไข |
|---|---|---|
| 401 ไม่ได้รับอนุญาต | คีย์ว่างหรือไม่ถูกต้อง; ตัวแปรสภาพแวดล้อมไม่ได้ถูกตั้งค่าใน shell ที่เปิดใช้งาน OpenCode | รัน echo $KIMICODE_API_KEY ในเทอร์มินัลเดียวกัน แล้วรีสตาร์ท OpenCode |
| 404 ไม่พบ | Base URL มี /chat/completions หรือขาด /v1 | ใช้ https://api.kimicode.top/v1 อย่างแม่นยำ |
| ไม่พบโมเดล | คีย์โมเดลไม่ตรงกับ uncensored | จับคู่คีย์ใน models กับ ID ที่ส่งกลับโดย GET /v1/models |
429 พร้อม concurrency | คำขอพร้อมกันมากเกินไป | ลดการเรียกใช้ฟังก์ชันแบบขนาน หรือรอให้สตรีมเสร็จสิ้น |
| คำขอมีขนาดใหญ่เกินไป | Body เกิน 8 MB หรือประวัติใกล้ขีดจำกัดหน้าต่างบริบท | เริ่มเซสชันใหม่หรือสรุปย่อประวัติการใช้งาน |
สำหรับหัวข้ออื่นที่ไม่ได้กล่าวไว้ที่นี่ หน้าเอกสาร มีข้อมูลการอ้างอิงคำขอแบบเต็ม และ คู่มือการผสานรวม ครอบคลุมเอนด์พอยต์เดียวกันจากมุมมองของไคลเอนต์สไตล์ OpenAI อื่นๆ
