根據 官方文檔 ，這個 function 是用來把一個 coroutine 跑在另一個 thread 上面的 event loop 裡面，然後他會 return 一個 Future object。

根據文檔我們可以快速的寫出一個 toy example：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

import asyncio
import threading

async def f():
    print("Inside coroutine f()")
    raise ValueError

def start_loop(loop):
    asyncio.set_event_loop(loop)
    loop.run_forever()

def main():
    loop = asyncio.new_event_loop()
    thread = threading.Thread(target=start_loop, args=(loop,))
    thread.start()

    future = asyncio.run_coroutine_threadsafe(f(), loop)

    try:
        future.result()
    except Exception as e:
        print("Caught exception:", repr(e))

    print("Stopping loop")
    loop.call_soon_threadsafe(loop.stop)
    thread.join()

if __name__ == "__main__":
    main()

main function 創了一個 thread 和一個 event loop，然後把 coroutine f 用 asyncio.run_coroutine_threadsafe 提交到該 event loop 上面，之後然後用 future.result() 拿結果，並 handle exceptions，最後把 event loop 停掉，看起來沒問題對吧。

執行結果如下：

Inside coroutine f()
Caught exception: ValueError()
Stopping loop

現在問題來了，如果我們在 coroutine f 裡面 raise 的不是 ValueError 而是 SystemExit 的話會怎麼樣？

根據 官方文檔 ，SystemExit 是繼承 BaseException 而不是 Exception，所以我們把第 21 行的 Exception 換成 BaseException 就好了？你會發現你改完這兩個地方之後再執行一次程式它會在 print 完 Inside coroutine f() 之後 hang 住，永遠不會結束。

我們必須去看 asyncio.run_coroutine_threadsafe 的 source code 才知道到底發生了什麼事情，我把該程式碼貼在這邊：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

def run_coroutine_threadsafe(coro, loop):
    """Submit a coroutine object to a given event loop.

    Return a concurrent.futures.Future to access the result.
    """
    if not coroutines.iscoroutine(coro):
        raise TypeError('A coroutine object is required')
    future = concurrent.futures.Future()

    def callback():
        try:
            futures._chain_future(ensure_future(coro, loop=loop), future)
        except (SystemExit, KeyboardInterrupt):
            raise
        except BaseException as exc:
            if future.set_running_or_notify_cancel():
                future.set_exception(exc)
            raise

    loop.call_soon_threadsafe(callback)
    return future

我們可以發現原來是這個 function 對於 SystemExit 和 KeyboardInterrupt 這兩個 exception 有特殊處理，是直接 raise，對於其他的 exception 則是會 call future.set_exception，因為他沒有 call set_exception，所以 future.result() 永遠拿不到結果。

我們稍微改寫一下原程式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

import time
import asyncio
import threading

async def f():
    print("Inside coroutine f()")
    raise SystemExit

def start_loop(loop):
    asyncio.set_event_loop(loop)
    loop.run_forever()

def main():
    loop = asyncio.new_event_loop()
    thread = threading.Thread(target=start_loop, args=(loop,))
    thread.start()

    future = asyncio.run_coroutine_threadsafe(f(), loop)

    try:
        future.result(timeout=3)
    except TimeoutError:
        print("Timeout")
        print("Future done?", future.done())
        print("Future cancelled?", future.cancelled())
        print("Loop alive?", loop.is_running())
        print("Thread alive?", thread.is_alive())
    except BaseException as e:
        print("Caught exception:", repr(e))

    print("Stopping loop")
    loop.call_soon_threadsafe(loop.stop)
    thread.join()

if __name__ == "__main__":
    main()

執行結果：

Inside coroutine f()
Timeout
Future done? False
Future cancelled? False
Loop alive? False
Thread alive? False
Stopping loop
Task exception was never retrieved
future: <Task finished name='Task-1' coro=<f() done, defined at /home/mortalhappiness/test/test.py:5> exception=SystemExit()>
Traceback (most recent call last):
  File "/home/mortalhappiness/miniforge3/envs/test/lib/python3.12/threading.py", line 1075, in _bootstrap_inner
    self.run()
  File "/home/mortalhappiness/miniforge3/envs/test/lib/python3.12/threading.py", line 1012, in run
    self._target(*self._args, **self._kwargs)
  File "/home/mortalhappiness/test/test.py", line 11, in start_loop
    loop.run_forever()
  File "/home/mortalhappiness/miniforge3/envs/test/lib/python3.12/asyncio/base_events.py", line 641, in run_forever
    self._run_once()
  File "/home/mortalhappiness/miniforge3/envs/test/lib/python3.12/asyncio/base_events.py", line 1986, in _run_once
    handle._run()
  File "/home/mortalhappiness/miniforge3/envs/test/lib/python3.12/asyncio/events.py", line 88, in _run
    self._context.run(self._callback, *self._args)
  File "/home/mortalhappiness/test/test.py", line 7, in f
    raise SystemExit
SystemExit

可以看到這個行為其實有點搞，因為 future.done() 和 future.cancelled() 都是 False，而 call future.result() 和 future.exception() 都會 hang 住不會有結果，但是你不 call 的話還會像上面一樣跳一個 warning 給你說 task exception was never retrieved，然後 event loop 和 thread 都還掛了。

結論

如果用 asyncio.run_coroutine_threadsafe 去執行 coroutine，而該 coroutine raise 了 SystemExit 或是 KeyboardInterrupt 的話，call future.result() 和 future.exception() 是沒用的，會永遠 hang 住。另外 thread 和 event loop 都會死掉，但是 main thread 不會死。

這次很高興透過貢獻 KubeRay 這個開源專案，得到了加入 Anyscale 遠端工作的機會。

在你繼續看下去之前，先給一些免責聲明，澆一下冷水，避免你看完期望太高。很多人都只寫好的一面，我不喜歡這樣。如果看完你還是想透過做開源這條路找到工作的話再看，否則其實已經可以離開了：

• 我是透過一位已經在 Anyscale 上班的朋友內推進去的。至於我是怎麼認識他，以及為何可以內推，會在內文說明。
• KubeRay 是 Anyscale 這間公司的產品之一。這代表你要去的公司跟你做的開源專案必須要有很強的相關性才有機會，不要想說隨便做一個開源就對找所有工作都有加分效果。
• 我還是需要面試，請不要覺得做開源就可以不用刷 LeetCode。你可能想問有人不用面試的嗎？有，我就有認識，但是不是每個人都可以這樣的。
• 我不是開源新手。如果你是開源新手，請不要預期你可以用跟我一樣短的時間快速上手專案，以免感到挫折。走上開源這條路，必須付出很多業餘的額外時間才有辦法。
• 這條路絕對不是尋常的路，也不是最輕鬆的路。如果要輕鬆的話，請刷 LeetCode 就好，CP 值絕對最高。如果想找外商工作，乖乖去美國讀書再去面試是最有效的。

KubeRay 專案介紹

KubeRay 是把 Ray 這個專案跑在 Kubernetes 上面的一個專案。而 Ray 是可以把 Python 的 function 自動跑在分散式的集群，是最近很紅的一個用來跑分散式 AI 和 Python apps 的框架。Ray 的背後商業公司就是 Anyscale。

下圖是今年 Ray Summit 介紹 KubeRay 的投影片的其中一頁，展示了現在社群的一些數字：

下圖是現在 Ray 的一些比較大的公司使用者，除了下圖的使用者之外，還有一些 Vendor 也有採用，例如 Google 的 GCP 和 Amazon 的 AWS。這些 Ray 的使用者裡面，大部分都是用 KubeRay 去部屬的！

我的開源貢獻背景

正如我前面所說，我不是開源新手。在貢獻 KubeRay 之前我已經貢獻過 Apache Submarine 和 Flyte 這兩個專案，而且都已經是 Committer 了。如果不知道 Committer 是什麼，簡單的說就是類似「核心貢獻者」，具有該專案寫入的權限，可以幫忙 merge pull requests。在 Apache Submarine 時期，我的 mentor 就包含了 蘇桓平 和 陳楷訓 等。當然還有其他 mentor 的幫助，不過本篇特別提這兩位是有原因的。蘇桓平同時也是我在貢獻 Flyte 專案時期的 mentor，而陳楷訓則是我在貢獻 KubeRay 時期的 mentor。

我大約是今年 4 月開始貢獻 KubeRay 的，KubeRay 基本上就是 Kubernetes Operator，這剛好跟我先前貢獻 Apache Submarine 的時候在做一樣的事。所以即使以前做 Apache Submarine 沒有得到工作，就學習技術的角度而言，我確實學到了一個帶著走的技能，而且還可以在其他專案上面用到。4 月到 9 月這期間我貢獻了大約 50 個 commits，雖然有一段是靠刷 linter issue 衝的，但其實這還是算滿多的，如果是開源新手的話不要想說可以有這個速度。

內推過程

我在前言裡面提到的已經在 Anyscale 上班的朋友就是陳楷訓，其實我們原本並不認識，最開始也是因為一起做 Apache Submarine 才認識的，所以這是做開源的其中一個好處：「擴展人脈」。其實台灣做開源的人很少，意思就是圈子很小，所以很容易可以認識圈內的人，因為基本上也就那些了。這些人脈就可以幫助到你。即使當初我並沒有因為做了 Apache Submarine 就拿到工作，但試想如果我當初沒有做的話，我也不會認識楷訓，也就不會有現在的工作了。

但為什麼他不能直接幫我內推，而是還需要我貢獻 KubeRay 之後，才能幫我內推呢？這是因為即使我跟他都有貢獻過 Apache Submarine 的經驗，有共事過，他也知道我的能力，但因為 Apache Submarine 這個專案跟 Anyscale 並沒有什麼關係，美國公司聘外國人遠端工作又很麻煩，所以如果做的專案本身沒有和公司有非常強的關聯，基本上沒有什麼加分效果，他去跟主管內推我，主管可能也不會答應給我面試機會。而 KubeRay 則不一樣，這個專案算是他們的產品之一，如果他們聘我的話，等於是獲得一位不用培訓就已經上手的工程師，對他們也有好處，而且他們也可以看到我之前的程式碼，畢竟如果程式碼寫太爛公司也不會想聘你對吧。

你說得這麼困難，為何你還要毅然前行？

• 做開源即使沒有拿到工作機會，也可以累積技術。
• 可以認識其他做開源的人，拓展人脈，或許有一天他們就會幫助到你。
• 我自己覺得做開源專案比做閉源專案有意義，應該說你的貢獻比較透明，容易被別人看見。

我看完了，即使我已經知道上面的限制，但我還是想鐵頭嘗試，要怎麼開始？

源來適你 是台灣致力於推廣開源的非營利社團，社群內有數位導師分別帶領大家參與貢獻不同的專案，我也是受到了很多社群成員的幫助，非常歡迎大家加入來看看！這邊也有 關於源來適你的資料彙整 ，可以參考看看！

致謝

本次毫無疑問，必須特別感謝 陳楷訓 的幫忙！之後我會繼續貢獻 Ray 和 KubeRay，希望之後對 Ray 熟一點之後，可以來寫一些關於 Ray 的技術文章！

client-go 是 Kubernetes 官方的 Golang client，負責跟 Kubernetes API server 用 REST API 的方式互動。其實 client-go 基本上可以做任何事情，不只是拿來寫 operator，連 kubectl 內部的實作也是用 client-go。至於更專門拿來寫 operator 的框架，包含 controller-runtime 、 kubebuilder 、 operator-sdk 會在本系列文的後續介紹。

Sample Controller 機制介紹

sample-controller 是 Kubernetes 官方使用 client-go 實作的範例 operator。

為了看懂程式碼，我們必須先了解我們自己寫的 operator 和 client-go 是怎麼互動的。這邊講的東西是 官方文件 的簡化版。

上面這張圖出自官方文件，網路上也可以查到許多教學都會提到這張圖。

上半部是 client-go 裡面的東西，看起來很複雜，有什麼 Reflctor、Informer、Indexer 之類的，但其實你只要知道 Informer 就好了。Informer 最主要的功能就是當 Resource 的狀態發生改變的時候通知我們。為什麼不是我們自己打 API 到 Kubernetes API server 就好了呢？這是因為打 API 到 Kubernetes API server 是一個很貴的操作，因此 Informer 內部有維護一個 Informer Cache，減少打 Requests 到 API server 的次數。

下半部是我們要自己寫的部份：

• Resource Event Handlers：當 Informer 通知我們某個 resource 的狀態改變的時候，我們應該做什麼事，基本上就是把它的 key（namespace + name）放進 workqueue 裡面。
• Workqueue：這個會存放所有待處理的 object 的 key，我們的 operator 會不斷的從裡面拿東西出來處理，然後試圖把叢集調整成我們想要的狀態，如果失敗的話可能需要再把這個 object key 加回去 workqueue 待會處理。

Sample Controller 程式碼解析

定義 CRD

在 register.go 定義 GroupName，然後 v1alpha1/types.go 定義 CRD 的 type。可以看到裡面定義了一個 Foo 的資源如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

// Foo is a specification for a Foo resource
type Foo struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   FooSpec   `json:"spec"`
	Status FooStatus `json:"status"`
}

// FooSpec is the spec for a Foo resource
type FooSpec struct {
	DeploymentName string `json:"deploymentName"`
	Replicas       *int32 `json:"replicas"`
}

// FooStatus is the status for a Foo resource
type FooStatus struct {
	AvailableReplicas int32 `json:"availableReplicas"`
}

除了 TypeMeta 和 ObjectMeta 這些基本的東西之外，多定義了 Spec 和 Status。Spec 是可以給使用者輸入的資料，定義的是「使用者期望這個資源最後該有的狀態」。Status 則是由我們的 Operator 去寫入值，代表的是「目前該資源的狀態」。

Sample Controller 使用了 Kubernetes 的 code-generator 來生成 CRD 的 typed client、informers、listers 和 deep-copy 函數。所以每次改動 types.go 的時候都要執行 ./hack/update-codegen.sh 來重新生成。

程式入口點

接著來看 main.go ，也就是程式的入口點，其實非常簡單，注意這幾行就好：

1
2
3
4
5
6
7
8

kubeClient, err := kubernetes.NewForConfig(cfg)
exampleClient, err := clientset.NewForConfig(cfg)
kubeInformerFactory := kubeinformers.NewSharedInformerFactory(kubeClient, time.Second*30)
exampleInformerFactory := informers.NewSharedInformerFactory(exampleClient, time.Second*30)
controller := NewController(ctx, kubeClient, exampleClient,
    kubeInformerFactory.Apps().V1().Deployments(),
    exampleInformerFactory.Samplecontroller().V1alpha1().Foos())
controller.Run(ctx, 2)

基本上就是創出 Kubernetes 內建 resource 以及我們自己建的這個 Foo Resource 的 client 和 informers，然後傳給 NewController。之後呼叫 controller.Run。

主要邏輯

最後來看最主要的部份， controller.go 。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

fooInformer.Informer().AddEventHandler(cache.ResourceEventHandlerFuncs{
    AddFunc: controller.enqueueFoo,
    UpdateFunc: func(old, new interface{}) {
        controller.enqueueFoo(new)
    },
})

deploymentInformer.Informer().AddEventHandler(cache.ResourceEventHandlerFuncs{
    AddFunc: controller.handleObject,
    UpdateFunc: func(old, new interface{}) {
        newDepl := new.(*appsv1.Deployment)
        oldDepl := old.(*appsv1.Deployment)
        if newDepl.ResourceVersion == oldDepl.ResourceVersion {
            // Periodic resync will send update events for all known Deployments.
            // Two different versions of the same Deployment will always have different RVs.
            return
        }
        controller.handleObject(new)
    },
    DeleteFunc: controller.handleObject,
})

這個就是上面講的 event handler，這邊可以註冊 AddFunc、UpdateFunc、DeleteFunc，informer 在偵測到 resource 狀態改變的時候會呼叫相對應的函數。可以看到這邊 fooInformer 都只是簡單的呼叫 enqueueFoo，而 deploymentInformer 都是呼叫 handleObject。

1
2
3
4
5
6
7
8

func (c *Controller) enqueueFoo(obj interface{}) {
	if objectRef, err := cache.ObjectToName(obj); err != nil {
		utilruntime.HandleError(err)
		return
	} else {
		c.workqueue.Add(objectRef)
	}
}

enqueueFoo 其實就是把 Foo 這個 object 的 key 存進 workqueue 而已，可以看這裡，非常明顯：

• cache.ObjectToName ：輸入一個 object，轉成 ObjectName。
• ObjectName ：就是 namespace + name 而已。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

func (c *Controller) handleObject(obj interface{}) {
	...
	if ownerRef := metav1.GetControllerOf(object); ownerRef != nil {
		// If this object is not owned by a Foo, we should not do anything more
		// with it.
		if ownerRef.Kind != "Foo" {
			return
		}

		foo, err := c.foosLister.Foos(object.GetNamespace()).Get(ownerRef.Name)
		if err != nil {
			logger.V(4).Info("Ignore orphaned object", "object", klog.KObj(object), "foo", ownerRef.Name)
			return
		}

		c.enqueueFoo(foo)
		return
	}
}

這個是 handleObject 的節錄，這邊做的事情是檢查這個 deployment 的 owner 是不是 Foo，如果不是的話我們就不管他，是的話就把對應的 Foo 的 key 加進 workqueue。這邊要帶到一個觀念叫做 OwnerRefernce ，在 Kubernetes 裡面，某些 object 是其他 object 的 owner，預設行為是當 owner 被刪除的時候，他 own 的其他 object 也會被刪除，例如 ReplicaSet 就是 Pod 的 owner，所以 ReplicaSet 被刪除的時候它管的 pods 也會被刪除。這也是為什麼上面的 fooInformer 沒有加上 DeleteFunc handler 的原因，因為當 Foo 被刪除的時候我們在這裡想做的事就是把他 own 的對應的所有 deployment 刪掉，但因為我們已經把 deployment 的 owner 設成 Foo，當 Foo 被刪掉的時候對應的 deployment 本來就也會被刪掉，所以我們不用特別處理。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

func (c *Controller) Run(ctx context.Context, workers int) error {
	...
	for i := 0; i < workers; i++ {
		go wait.UntilWithContext(ctx, c.runWorker, time.Second)
	}
	...
}

func (c *Controller) runWorker(ctx context.Context) {
	for c.processNextWorkItem(ctx) {
	}
}

Run 就是 main.go 呼叫 controller 的入口點，會起多個 goruntine 跑 runWorker。runWorker 其實就只是跑一個無窮迴圈不斷執行 processNextWorkItem 而已。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

func (c *Controller) processNextWorkItem(ctx context.Context) bool {
	objRef, shutdown := c.workqueue.Get()

	...

	// Run the syncHandler, passing it the structured reference to the object to be synced.
	err := c.syncHandler(ctx, objRef)
	if err == nil {
		c.workqueue.Forget(objRef)
		logger.Info("Successfully synced", "objectName", objRef)
		return true
	}
	utilruntime.HandleErrorWithContext(ctx, err, "Error syncing; requeuing for later retry", "objectReference", objRef)
	c.workqueue.AddRateLimited(objRef)
	return true
}

上面是 processNextWorkItem 的節錄，首先就是先從 workqueue 拿一個 object key 出來，然後呼叫 syncHandler 處理，如果成功的話就把它從 workqueue 裡面忘掉，不然就要做 error handling 然後放回去 workqueue 等等處理。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

func (c *Controller) syncHandler(ctx context.Context, objectRef cache.ObjectName) error {
	...

	// Get the Foo resource with this namespace/name
	foo, err := c.foosLister.Foos(objectRef.Namespace).Get(objectRef.Name)

	...

	deploymentName := foo.Spec.DeploymentName

	...

	// Get the deployment with the name specified in Foo.spec
	deployment, err := c.deploymentsLister.Deployments(foo.Namespace).Get(deploymentName)
	// If the resource doesn't exist, we'll create it
	if errors.IsNotFound(err) {
		deployment, err = c.kubeclientset.AppsV1().Deployments(foo.Namespace).Create(context.TODO(), newDeployment(foo), metav1.CreateOptions{FieldManager: FieldManager})
	}

	if err != nil {
		return err
	}

	// If the Deployment is not controlled by this Foo resource, we should log
	// a warning to the event recorder and return error msg.
	if !metav1.IsControlledBy(deployment, foo) {
		msg := fmt.Sprintf(MessageResourceExists, deployment.Name)
		c.recorder.Event(foo, corev1.EventTypeWarning, ErrResourceExists, msg)
		return fmt.Errorf("%s", msg)
	}

	// If this number of the replicas on the Foo resource is specified, and the
	// number does not equal the current desired replicas on the Deployment, we
	// should update the Deployment resource.
	if foo.Spec.Replicas != nil && *foo.Spec.Replicas != *deployment.Spec.Replicas {
		logger.V(4).Info("Update deployment resource", "currentReplicas", *foo.Spec.Replicas, "desiredReplicas", *deployment.Spec.Replicas)
		deployment, err = c.kubeclientset.AppsV1().Deployments(foo.Namespace).Update(context.TODO(), newDeployment(foo), metav1.UpdateOptions{FieldManager: FieldManager})
	}

	if err != nil {
		return err
	}

	// Finally, we update the status block of the Foo resource to reflect the
	// current state of the world
	err = c.updateFooStatus(foo, deployment)
	if err != nil {
		return err
	}

	c.recorder.Event(foo, corev1.EventTypeNormal, SuccessSynced, MessageResourceSynced)
	return nil
}

最後是 syncHandler 的節錄，這邊就是我們真正要寫的邏輯，把叢集調整成使用者在 Spec 裡面宣告的狀態。這邊想要的狀態就是在 Spec 裡面宣告的 deployment 有被創出來，且 replica 的數量和 Spec 裡面宣告的一致。

結語

看完之後，是不是覺得我好像只講了 Sample Controller 的程式碼一小部份？其實這是因為 client-go 算是很底層的 library，用來寫 operator 的話有一些缺點：

• 我們真正需要寫自己的邏輯地方沒有那麼多，但還是必須寫上某些固定要寫的東西，導致有些地方有點冗餘。
• 要監聽不同資源的時候，必須對每個資源都宣告 informers、listers 之類重複的東西，例如 Sample Controller 裡面就宣告了 fooInformer 和 deploymentInformer，要管的資源一多的話非常麻煩。

這些缺點也催生了其他更專門拿來寫 operator 的框架，包含 controller-runtime 、 kubebuilder 、 operator-sdk 等，歡迎關注本系列文的後續介紹來了解這些框架。

參考資料

• https://github.com/kubernetes/sample-controller/blob/master/docs/controller-client-go.md
• https://www.linkedin.com/pulse/kubernetes-custom-controllers-part-1-kritik-sachdeva/
• https://www.linkedin.com/pulse/kubernetes-custom-controller-part-2-kritik-sachdeva/

若只想看結論，請直接跳到 總結 。請注意本文所述內容只確保版本 0.3.2 可以用，沒有測試過其他版本。

簡介

GraphRAG 是微軟釋出的一種新的 RAG (Retrieval-Augmented Generation) 技術，對比於一般的 RAG 作法是把文本切塊然後向量化存在 vector store，查詢的時候把使用者的輸入也向量化然後再去比較相似度，GraphRAG 則是從文本之中提取出資訊並建成一個 Knowledge Graph，優點是可以更好的理解不同文本之間複雜的關聯性。

直至撰文當下，官方最新的版本為 0.3.2，這是 GitHub Repository 的對應版本 0.3.2 的連結 ，本文所述內容或許其他版本也可以用，但不保證。

如果你看了官方文件的教學就會發現，0.3.2 的官方設定只支援 OpenAI 和 Azure OpenAI，你需要在 config file 裡面放進你的 API Key，這樣雖然可以用，也最簡單，但是 GraphRAG 在 Indexing 的時候需要頻繁呼叫 LLM，所以這樣會很貴，而且沒辦法用自己 fine tune 的模型。

那有沒有辦法用跑在本地的開源模型例如 Llama 3.1 呢？結論是有，但是你需要先踩一堆坑，因為官方的實作現在並不支援本地的模型，需要自己魔改一些東西。

你可能會問說為什麼不用 LangChain 裡面的 LLMGraphTransformer 呢？我只能說畢竟現在它還是 experimental 的功能，跟微軟官方的實作還是有點差距。有興趣的話可以看下面這幾個連結：

• https://python.langchain.com/v0.2/docs/how_to/graph_constructing/
• https://python.langchain.com/v0.2/docs/tutorials/graph/

先備條件

• 安裝好 Ollama 然後把它跑起來。
• 一個 LLM 模型，例如 ollama pull llama3.1:8b。
• 一個 Text Embedding 模型，例如 ollama pull nomic-embed-text。

踩坑過程

當我一開始打開 Get Started 頁面，滿心歡喜的發現看起來非常的短，應該很快就可以弄好。現在來看那時候的我真是太天真了…

首先這幾步都沒有問題：

pip install graphrag
mkdir -p ./ragtest/input
curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt > ./ragtest/input/book.txt
python -m graphrag.index --init --root ./ragtest

接下來要編輯 settings.yaml，第一個問題來了，model 要怎麼填呢？

首先把 .env 刪了，因為我們並不需要 API key。

然後打開 settings.yaml，寫入以下內容：

View settings.yaml on GitHub Gist

幾個跟原本的 settings.yaml 不同的地方：

• llm
  • api_key: 隨便亂設，不重要，因為我們不會呼叫 API，而是查詢本地的模型，這裡我設成 NONE。
  • model: 設成你的本地 LLM 模型，例如 llama3.1:8b。
  • max_tokens: 這個數字要設成小於你的 LLM 模型可接受的最大 Token 數量。
  • api_base: 設成 http://localhost:11434/v1。
• embeddings
  • llm
    • api_key: 隨便亂設，不重要，因為我們不會呼叫 API，而是查詢本地的模型，這裡我設成 NONE。
  • model: 設成你的本地 Text Embedding 模型，例如 nomic-embed-text。
  • api_base: 設成 http://localhost:11434/api。
  • batch_max_tokens: 這個數字要設成小於你的 Text Embedding 模型可接受的最大 Token 數量。
• chunks

  • size：下調成 300，沒有調的話會噴以下 error，相關 issue： https://github.com/microsoft/graphrag/issues/362

    09:44:07,997 datashaper.workflow.workflow ERROR Error executing verb "cluster_graph" in create_base_entity_graph: Columns must be same length as key
    Traceback (most recent call last):
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/datashaper/workflow/workflow.py", line 410, in _execute_verb
        result = node.verb.func(**verb_args)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/graph/clustering/cluster_graph.py", line 102, in cluster_graph
        output_df[[level_to, to]] = pd.DataFrame(
        ~~~~~~~~~^^^^^^^^^^^^^^^^
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/pandas/core/frame.py", line 4299, in __setitem__
        self._setitem_array(key, value)
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/pandas/core/frame.py", line 4341, in _setitem_array
        check_key_length(self.columns, key, value)
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/pandas/core/indexers/utils.py", line 390, in check_key_length
        raise ValueError("Columns must be same length as key")
    ValueError: Columns must be same length as key
    16:25:46,215 graphrag.index.reporting.file_workflow_callbacks INFO Error executing verb "cluster_graph" in create_base_entity_graph: Columns must be same length as key details=None
    16:25:46,216 graphrag.index.run ERROR error running workflow create_base_entity_graph
    Traceback (most recent call last):
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/run.py", line 325, in run_pipeline
        result = await workflow.run(context, callbacks)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/datashaper/workflow/workflow.py", line 369, in run
        timing = await self._execute_verb(node, context, callbacks)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/datashaper/workflow/workflow.py", line 410, in _execute_verb
        result = node.verb.func(**verb_args)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/graph/clustering/cluster_graph.py", line 102, in cluster_graph
        output_df[[level_to, to]] = pd.DataFrame(
        ~~~~~~~~~^^^^^^^^^^^^^^^^
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/pandas/core/frame.py", line 4299, in __setitem__
        self._setitem_array(key, value)
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/pandas/core/frame.py", line 4341, in _setitem_array
        check_key_length(self.columns, key, value)
      File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/pandas/core/indexers/utils.py", line 390, in check_key_length
        raise ValueError("Columns must be same length as key")
    ValueError: Columns must be same length as key
    

改完設定後，開心的執行 python -m graphrag.index --init --root ./ragtest，就會發現噴了以下的 error：

09:19:54,508 datashaper.workflow.workflow ERROR Error executing verb "text_embed" in create_final_entities: 'NoneType' object is not iterable
Traceback (most recent call last):
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/datashaper/workflow/workflow.py", line 415, in _execute_verb
    result = await result
             ^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/text/embed/text_embed.py", line 105, in text_embed
    return await _text_embed_in_memory(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/text/embed/text_embed.py", line 130, in _text_embed_in_memory
    result = await strategy_exec(texts, callbacks, cache, strategy_args)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/text/embed/strategies/openai.py", line 62, in run
    embeddings = await _execute(llm, text_batches, ticker, semaphore)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/text/embed/strategies/openai.py", line 106, in _execute
    results = await asyncio.gather(*futures)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/text/embed/strategies/openai.py", line 100, in embed
    chunk_embeddings = await llm(chunk)
                       ^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/caching_llm.py", line 96, in __call__
    result = await self._delegate(input, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/rate_limiting_llm.py", line 177, in __call__
    result, start = await execute_with_retry()
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/rate_limiting_llm.py", line 159, in execute_with_retry
    async for attempt in retryer:
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/tenacity/asyncio/__init__.py", line 166, in __anext__
    do = await self.iter(retry_state=self._retry_state)
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/tenacity/asyncio/__init__.py", line 153, in iter
    result = await action(retry_state)
             ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/tenacity/_utils.py", line 99, in inner
    return call(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/tenacity/__init__.py", line 398, in <lambda>
    self._add_action_func(lambda rs: rs.outcome.result())
                                     ^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/concurrent/futures/_base.py", line 449, in result
    return self.__get_result()
           ^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/concurrent/futures/_base.py", line 401, in __get_result
    raise self._exception
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/rate_limiting_llm.py", line 165, in execute_with_retry
    return await do_attempt(), start
           ^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/rate_limiting_llm.py", line 147, in do_attempt
    return await self._delegate(input, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/base_llm.py", line 49, in __call__
    return await self._invoke(input, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/base_llm.py", line 53, in _invoke
    output = await self._execute_llm(input, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/openai/openai_embeddings_llm.py", line 36, in _execute_llm
    embedding = await self.client.embeddings.create(
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/resources/embeddings.py", line 237, in create
    return await self._post(
           ^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/_base_client.py", line 1816, in post
    return await self.request(cast_to, opts, stream=stream, stream_cls=stream_cls)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/_base_client.py", line 1510, in request
    return await self._request(
           ^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/_base_client.py", line 1613, in _request
    return await self._process_response(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/_base_client.py", line 1710, in _process_response
    return await api_response.parse()
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/_response.py", line 420, in parse
    parsed = self._options.post_parser(parsed)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/resources/embeddings.py", line 225, in parser
    for embedding in obj.data:
TypeError: 'NoneType' object is not iterable
09:19:54,533 graphrag.index.reporting.file_workflow_callbacks INFO Error executing verb "text_embed" in create_final_entities: 'NoneType' object is not iterable details=None
09:19:54,541 graphrag.index.run ERROR error running workflow create_final_entities
Traceback (most recent call last):
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/run.py", line 325, in run_pipeline
    result = await workflow.run(context, callbacks)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/datashaper/workflow/workflow.py", line 369, in run
    timing = await self._execute_verb(node, context, callbacks)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/datashaper/workflow/workflow.py", line 415, in _execute_verb
    result = await result
             ^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/text/embed/text_embed.py", line 105, in text_embed
    return await _text_embed_in_memory(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/text/embed/text_embed.py", line 130, in _text_embed_in_memory
    result = await strategy_exec(texts, callbacks, cache, strategy_args)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/text/embed/strategies/openai.py", line 62, in run
    embeddings = await _execute(llm, text_batches, ticker, semaphore)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/text/embed/strategies/openai.py", line 106, in _execute
    results = await asyncio.gather(*futures)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/index/verbs/text/embed/strategies/openai.py", line 100, in embed
    chunk_embeddings = await llm(chunk)
                       ^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/caching_llm.py", line 96, in __call__
    result = await self._delegate(input, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/rate_limiting_llm.py", line 177, in __call__
    result, start = await execute_with_retry()
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/rate_limiting_llm.py", line 159, in execute_with_retry
    async for attempt in retryer:
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/tenacity/asyncio/__init__.py", line 166, in __anext__
    do = await self.iter(retry_state=self._retry_state)
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/tenacity/asyncio/__init__.py", line 153, in iter
    result = await action(retry_state)
             ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/tenacity/_utils.py", line 99, in inner
    return call(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/tenacity/__init__.py", line 398, in <lambda>
    self._add_action_func(lambda rs: rs.outcome.result())
                                     ^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/concurrent/futures/_base.py", line 449, in result
    return self.__get_result()
           ^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/concurrent/futures/_base.py", line 401, in __get_result
    raise self._exception
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/rate_limiting_llm.py", line 165, in execute_with_retry
    return await do_attempt(), start
           ^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/rate_limiting_llm.py", line 147, in do_attempt
    return await self._delegate(input, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/base_llm.py", line 49, in __call__
    return await self._invoke(input, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/base/base_llm.py", line 53, in _invoke
    output = await self._execute_llm(input, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/openai/openai_embeddings_llm.py", line 36, in _execute_llm
    embedding = await self.client.embeddings.create(
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/resources/embeddings.py", line 237, in create
    return await self._post(
           ^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/_base_client.py", line 1816, in post
    return await self.request(cast_to, opts, stream=stream, stream_cls=stream_cls)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/_base_client.py", line 1510, in request
    return await self._request(
           ^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/_base_client.py", line 1613, in _request
    return await self._process_response(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/_base_client.py", line 1710, in _process_response
    return await api_response.parse()
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/_response.py", line 420, in parse
    parsed = self._options.post_parser(parsed)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/openai/resources/embeddings.py", line 225, in parser
    for embedding in obj.data:
TypeError: 'NoneType' object is not iterable

解法參考自 https://github.com/microsoft/graphrag/issues/370#issuecomment-2211821370

留言說要把某個檔案的內容換掉，但我覺得這樣不太好，因為這樣有一天你想用套件原本的功能反而可能會出問題，所以我用外部 monkey patch 的方式，首先創一個檔案叫做 monkey_patch.py，寫入以下內容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

def patch_openai_embeddings_llm():
    from graphrag.llm.openai.openai_embeddings_llm import OpenAIEmbeddingsLLM
    import ollama

    async def _execute_llm(self, input, **kwargs):
        embedding_list = []
        for inp in input:
            embedding = ollama.embeddings(model=self.configuration.model, prompt=inp)
            embedding_list.append(embedding["embedding"])
        return embedding_list

    OpenAIEmbeddingsLLM._execute_llm = _execute_llm

記得執行 pip install ollama。

我們下載 graphrag.index 這個 CLI 的內容，然後 monkey patch 它。

先執行

wget https://raw.githubusercontent.com/microsoft/graphrag/v0.3.2/graphrag/index/__main__.py -O index.py

然後把第 8 行的 from .cli import index_cli 換成下面的內容：

1
2
3

from graphrag.index.cli import index_cli
from monkey_patch import patch_openai_embeddings_llm
patch_openai_embeddings_llm()

接著執行 python index.py --root ./ragtest，終於沒有 error 了！

試著執行 Global Query

python -m graphrag.query \
--root ./ragtest \
--method global \
"What are the top themes in this story?"

發生這個 error

Traceback (most recent call last):
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/openai/utils.py", line 130, in try_parse_json_object
    result = json.loads(input)
             ^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 337, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 355, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
not expected dict type. type=<class 'str'>:
Traceback (most recent call last):
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/openai/utils.py", line 130, in try_parse_json_object
    result = json.loads(input)
             ^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 337, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 355, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
not expected dict type. type=<class 'str'>:
Traceback (most recent call last):
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/openai/utils.py", line 130, in try_parse_json_object
    result = json.loads(input)
             ^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 337, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 355, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
not expected dict type. type=<class 'str'>:
Traceback (most recent call last):
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/openai/utils.py", line 130, in try_parse_json_object
    result = json.loads(input)
             ^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 337, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 355, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
not expected dict type. type=<class 'str'>:
Traceback (most recent call last):
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/openai/utils.py", line 130, in try_parse_json_object
    result = json.loads(input)
             ^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 337, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 355, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
not expected dict type. type=<class 'str'>:
Traceback (most recent call last):
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/llm/openai/utils.py", line 130, in try_parse_json_object
    result = json.loads(input)
             ^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 337, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/json/decoder.py", line 355, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

試著執行 Local Query

python -m graphrag.query \
--root ./ragtest \
--method local \
"Who is Scrooge, and what are his main relationships?"

發生這個 error

Error embedding chunk {'OpenAIEmbedding': "'NoneType' object is not iterable"}
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/__main__.py", line 92, in <module>
    run_local_search(
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/cli.py", line 164, in run_local_search
    response, context_data = asyncio.run(
                             ^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/asyncio/runners.py", line 190, in run
    return runner.run(main)
           ^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/asyncio/runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/asyncio/base_events.py", line 654, in run_until_complete
    return future.result()
           ^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/api.py", line 222, in local_search
    result: SearchResult = await search_engine.asearch(query=query)
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/structured_search/local_search/search.py", line 67, in asearch
    context_text, context_records = self.context_builder.build_context(
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/structured_search/local_search/mixed_context.py", line 139, in build_context
    selected_entities = map_query_to_entities(
                        ^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/context_builder/entity_extraction.py", line 55, in map_query_to_entities
    search_results = text_embedding_vectorstore.similarity_search_by_text(
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/vector_stores/lancedb.py", line 118, in similarity_search_by_text
    query_embedding = text_embedder(text)
                      ^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/context_builder/entity_extraction.py", line 57, in <lambda>
    text_embedder=lambda t: text_embedder.embed(t),
                            ^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/llm/oai/embedding.py", line 96, in embed
    chunk_embeddings = np.average(chunk_embeddings, axis=0, weights=chunk_lens)
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/numpy/lib/function_base.py", line 550, in average
    raise ZeroDivisionError(
ZeroDivisionError: Weights sum to zero, can't be normalized

所以只好再來 monkey patch query CLI 了，相關的 issue 留言：

• https://github.com/microsoft/graphrag/issues/345#issuecomment-2230317752
• https://github.com/microsoft/graphrag/issues/575#issuecomment-2252045859

在 monkey_patch.py 裡面新增兩個 Function 如下：

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

def patch_query_embedding():
    from graphrag.query.llm.oai.embedding import OpenAIEmbedding
    import ollama
    from tenacity import (
        AsyncRetrying,
        RetryError,
        Retrying,
        retry_if_exception_type,
        stop_after_attempt,
        wait_exponential_jitter,
    )

    def _embed_with_retry(self, text, **kwargs):
        try:
            retryer = Retrying(
                stop=stop_after_attempt(self.max_retries),
                wait=wait_exponential_jitter(max=10),
                reraise=True,
                retry=retry_if_exception_type(self.retry_error_types),
            )
            for attempt in retryer:
                with attempt:
                    embedding = (ollama.embeddings(model=self.model, prompt=text)["embedding"] or [])
                    return (embedding, len(text))
        except RetryError as e:
            self._reporter.error(
                message="Error at embed_with_retry()",
                details={self.__class__.__name__: str(e)},
            )
            return ([], 0)
        else:
            # TODO: why not just throw in this case?
            return ([], 0)

    async def _aembed_with_retry(self, text, **kwargs):
        try:
            retryer = AsyncRetrying(
                stop=stop_after_attempt(self.max_retries),
                wait=wait_exponential_jitter(max=10),
                reraise=True,
                retry=retry_if_exception_type(self.retry_error_types),
            )
            async for attempt in retryer:
                with attempt:
                    embedding = (ollama.embeddings(model=self.model, prompt=text)["embedding"] or [])
                    return (embedding, len(text))
        except RetryError as e:
            self._reporter.error(
                message="Error at embed_with_retry()",
                details={self.__class__.__name__: str(e)},
            )
            return ([], 0)
        else:
            # TODO: why not just throw in this case?
            return ([], 0)

    OpenAIEmbedding._embed_with_retry = _embed_with_retry
    OpenAIEmbedding._aembed_with_retry = _aembed_with_retry

def patch_global_search():
    from graphrag.query.structured_search.global_search.search import GlobalSearch
    import logging
    import time
    from graphrag.query.llm.text_utils import num_tokens
    from graphrag.query.structured_search.base import SearchResult
    log = logging.getLogger(__name__)

    async def _map_response_single_batch(self, context_data, query, **llm_kwargs):
        """Generate answer for a single chunk of community reports."""
        start_time = time.time()
        search_prompt = ""
        try:
            search_prompt = self.map_system_prompt.format(context_data=context_data)
            search_messages = [ {"role": "user", "content": search_prompt + "\n\n### USER QUESTION ### \n\n" + query} ]
            async with self.semaphore:
                search_response = await self.llm.agenerate(
                    messages=search_messages, streaming=False, **llm_kwargs
                )
                log.info("Map response: %s", search_response)
            try:
                # parse search response json
                processed_response = self.parse_search_response(search_response)
            except ValueError:
                # Clean up and retry parse
                try:
                    # parse search response json
                    processed_response = self.parse_search_response(search_response)
                except ValueError:
                    log.warning(
                        "Warning: Error parsing search response json - skipping this batch"
                    )
                    processed_response = []

            return SearchResult(
                response=processed_response,
                context_data=context_data,
                context_text=context_data,
                completion_time=time.time() - start_time,
                llm_calls=1,
                prompt_tokens=num_tokens(search_prompt, self.token_encoder),
            )

        except Exception:
            log.exception("Exception in _map_response_single_batch")
            return SearchResult(
                response=[{"answer": "", "score": 0}],
                context_data=context_data,
                context_text=context_data,
                completion_time=time.time() - start_time,
                llm_calls=1,
                prompt_tokens=num_tokens(search_prompt, self.token_encoder),
            )

    GlobalSearch._map_response_single_batch = _map_response_single_batch

執行

wget https://raw.githubusercontent.com/microsoft/graphrag/v0.3.2/graphrag/query/__main__.py -O query.py

然後把第 9 行的 from .cli import run_global_search, run_local_search 換成以下內容

1
2
3
4

from graphrag.query.cli import run_global_search, run_local_search
from monkey_patch import patch_query_embedding, patch_global_search
patch_query_embedding()
patch_global_search()

然後執行 Global 和 Local Search，Local Search 看起來還不錯，Global Search 看起來不是很好，可能參數還需要再調整一下，不過至少沒有 error 了！

$ python query.py --root ./ragtest --method global "What are the top themes in this story?"

INFO: Reading settings from ragtest/settings.yaml
/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/indexer_adapters.py:71: SettingWithCopyWarning:
A value is trying to be set on a copy of a slice from a DataFrame.
Try using .loc[row_indexer,col_indexer] = value instead

See the caveats in the documentation: https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#returning-a-view-versus-a-copy
  entity_df["community"] = entity_df["community"].fillna(-1)
/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/indexer_adapters.py:72: SettingWithCopyWarning:
A value is trying to be set on a copy of a slice from a DataFrame.
Try using .loc[row_indexer,col_indexer] = value instead

See the caveats in the documentation: https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#returning-a-view-versus-a-copy
  entity_df["community"] = entity_df["community"].astype(int)
creating llm client with {'api_key': 'REDACTED,len=4', 'type': "openai_chat", 'model': 'llama3.1:8b', 'max_tokens': 8191, 'temperature': 0.0, 'top_p': 1.0, 'n': 1, 'request_timeout': 180.0, 'api_base': 'http://localhost:11434/v1', 'api_version': None, 'organization': None, 'proxy': None, 'cognitive_services_endpoint': None, 'deployment_name': None, 'model_supports_json': True, 'tokens_per_minute': 0, 'requests_per_minute': 0, 'max_retries': 10, 'max_retry_wait': 10.0, 'sleep_on_rate_limit_recommendation': True, 'concurrent_requests': 25}

SUCCESS: Global Search Response:
You didn't provide a story. Please share the text, and I'll be happy to help you identify the top themes.

$ python query.py --root ./ragtest --method local "Who is Scrooge, and what are his main relationships?"

INFO: Reading settings from ragtest/settings.yaml

INFO: Vector Store Args: {}
/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/indexer_adapters.py:71: SettingWithCopyWarning:
A value is trying to be set on a copy of a slice from a DataFrame.
Try using .loc[row_indexer,col_indexer] = value instead

See the caveats in the documentation: https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#returning-a-view-versus-a-copy
  entity_df["community"] = entity_df["community"].fillna(-1)
/home/chishengliu/miniforge3/envs/graphrag/lib/python3.11/site-packages/graphrag/query/indexer_adapters.py:72: SettingWithCopyWarning:
A value is trying to be set on a copy of a slice from a DataFrame.
Try using .loc[row_indexer,col_indexer] = value instead

See the caveats in the documentation: https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#returning-a-view-versus-a-copy
  entity_df["community"] = entity_df["community"].astype(int)
creating llm client with {'api_key': 'REDACTED,len=4', 'type': "openai_chat", 'model': 'llama3.1:8b', 'max_tokens': 8191, 'temperature': 0.0, 'top_p': 1.0, 'n': 1, 'request_timeout': 180.0, 'api_base': 'http://localhost:11434/v1', 'api_version': None, 'organization': None, 'proxy': None, 'cognitive_services_endpoint': None, 'deployment_name': None, 'model_supports_json': True, 'tokens_per_minute': 0, 'requests_per_minute': 0, 'max_retries': 10, 'max_retry_wait': 10.0, 'sleep_on_rate_limit_recommendation': True, 'concurrent_requests': 25}
creating embedding llm client with {'api_key': 'REDACTED,len=4', 'type': "openai_embedding", 'model': 'nomic-embed-text', 'max_tokens': 4000, 'temperature': 0, 'top_p': 1, 'n': 1, 'request_timeout': 180.0, 'api_base': 'http://localhost:11434/api', 'api_version': None, 'organization': None, 'proxy': None, 'cognitive_services_endpoint': None, 'deployment_name': None, 'model_supports_json': None, 'tokens_per_minute': 0, 'requests_per_minute': 0, 'max_retries': 10, 'max_retry_wait': 10.0, 'sleep_on_rate_limit_recommendation': True, 'concurrent_requests': 25}

SUCCESS: Local Search Response:
A classic character!

Ebenezer Scrooge is the main protagonist of Charles Dickens' novella "A Christmas Carol". He is a miserly and bitter old man who lives in London during the Victorian era. Scrooge is known for his extreme love of money, his disdain for charity and kindness, and his general grumpiness.

Scrooge's main relationships are:

1. **Jacob Marley**: The ghost of his deceased business partner, who appears to Scrooge on Christmas Eve to warn him about the consequences of his selfish ways.
2. **Bob Cratchit**: His underpaid and overworked clerk, who is struggling to provide for his large family during the holiday season. Scrooge's treatment of Bob is particularly cruel, as he pays him a meager salary and expects him to work long hours without complaint.
3. **Tiny Tim**: The youngest son of Bob Cratchit, who suffers from illness and poverty. Scrooge's heartlessness towards Tiny Tim serves as a catalyst for his transformation in the story.
4. **His nephew, Fred**: A kind and generous young man who invites Scrooge to join him for Christmas dinner, but is rebuffed by his miserly uncle.
5. **The Ghosts of Christmas Past, Present, and Yet to Come**: Three supernatural visitations that haunt Scrooge on Christmas Eve, forcing him to confront the consequences of his actions and the possibility of a better future.

Through these relationships, Dickens explores themes of redemption, kindness, and the importance of human connection in "A Christmas Carol".

總結

本文章的程式碼都放在 這個 Gist 裡面，總結一下完整的步驟為：

• 照著官方的 Get Started 跑完 python -m graphrag.index --init --root ./ragtest
• 把 settings.yaml 換成 Gist 裡面的 settings.yaml
• 執行

  wget https://raw.githubusercontent.com/microsoft/graphrag/v0.3.2/graphrag/index/__main__.py -O index.py
  

• 執行

  wget https://raw.githubusercontent.com/microsoft/graphrag/v0.3.2/graphrag/query/__main__.py -O query.py
  

• 下載 Gist 裡面的 graphrag_monkey_patch.py
• 把 index.py 的第 8 行換成

  1 2 3

  from graphrag.index.cli import index_cli from graphrag_monkey_patch import patch_graphrag patch_graphrag()

• 把 query.py 的第 9 行換成

  1 2 3

  from graphrag.query.cli import run_global_search, run_local_search from graphrag_monkey_patch import patch_graphrag patch_graphrag()

• 之後遇到要使用 python -m graphrag.index 的時候都換成用 python index.py，遇到要使用 python -m graphrag.query 的時候都換成用 python query.py 即可。

這邊假設你已經對 Kubernetes 有基本的認識，知道怎麼用 kubectl。Pod、ReplicaSet、Service，甚至是 Namespace 其實都是一種 API Resource。

可以用 kubectl api-resources 來查看現在 Kubernetes 裡面存在的所有 API Resources。

$ kubectl api-resources
NAME                     SHORTNAMES   APIVERSION   NAMESPACED   KIND
bindings                              v1           true         Binding
componentstatuses        cs           v1           false        ComponentStatus
configmaps               cm           v1           true         ConfigMap
endpoints                ep           v1           true         Endpoints
events                   ev           v1           true         Event
limitranges              limits       v1           true         LimitRange
namespaces               ns           v1           false        Namespace
nodes                    no           v1           false        Node
persistentvolumeclaims   pvc          v1           true         PersistentVolumeClaim
persistentvolumes        pv           v1           false        PersistentVolume
pods                     po           v1           true         Pod
podtemplates                          v1           true         PodTemplate
replicationcontrollers   rc           v1           true         ReplicationController
resourcequotas           quota        v1           true         ResourceQuota
secrets                               v1           true         Secret
serviceaccounts          sa           v1           true         ServiceAccount
services                 svc          v1           true         Service
...

Kubernetes Custom Resources

Custom Resources，顧名思義是指我們可以創造自定義的 API Resources 安裝到 Kubernetes 裡面來擴充它。

根據官方文件，創造 Custom Resources 有兩種方式，但最常用的是使用 Custom Resource Definition (CRD)，因此這邊只討論 CRD。

其實 CRD 自己本身也是一種 API Resource，藉由以下指令便可以很清楚看到：

$ kubectl api-resources | grep -i custom
customresourcedefinitions   crd,crds   apiextensions.k8s.io/v1   false   CustomResourceDefinition

想想我們平常是怎麼創建 Resources 的，通常是直接寫一個 YAML 檔，然後直接用 kubectl apply 去創建，所以其實創建 CRD 的步驟也一樣。

首先創建一個檔案叫做 chishengliu-crd.yaml，內容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: chishenglius.chishengliu.com
spec:
  group: chishengliu.com
  scope: Namespaced
  names:
    plural: chishenglius
    singular: chishengliu
    kind: ChiShengLiu
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                mood:
                  type: string

之後執行以下指令

$ kubectl apply -f chishengliu-crd.yaml
customresourcedefinition.apiextensions.k8s.io/chishenglius.chishengliu.com created

$ kubectl api-resources | grep -i chishengliu
chishenglius   chishengliu.com/v1   true   ChiShengLiu

可以發現現在叢集裡面就多一個新的 Resouce 叫做 ChiShengLiu 了。

然後要創建 ChiShengLiu 這種 Resource 的話，一樣是寫一個 YAML 檔然後 kubectl apply。創一個檔案叫做 happy-chishengliu.yaml，內容如下：

1
2
3
4
5
6

apiVersion: chishengliu.com/v1
kind: ChiShengLiu
metadata:
  name: happy-chishengliu
spec:
  mood: "happy"

然後執行以下指令：

$ kubectl apply -f happy-chishengliu.yaml
chishengliu.chishengliu.com/happy-chishengliu created

$ kubectl describe chishengliu happy-chishengliu
Name:         happy-chishengliu
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  chishengliu.com/v1
Kind:         ChiShengLiu
Metadata:
  Creation Timestamp:  2024-08-28T17:37:57Z
  Generation:          1
  Resource Version:    1609
  UID:                 3cbc6964-2c7b-4e60-b113-4fa5f4dd0b3c
Spec:
  Mood:  happy
Events:  <none>

可以看到我們創了一個 ChiShengLiu 的 Resource，名字是 happy-chishengliu。

Kubernetes Operator

空有 Custom Resource 並沒有任何用處，可以發現我們創了這個 ChiShengLiu 的 Resource 之後，Kubernetes 叢集並沒有發生任何變化，與內建的 Resources 非常不同。

內建的 Resources 之所以會有功能，是因為叢集裡面有對應的 Controller 在運作，Controller 的工作是負責監聽叢集內的某些 Resources，然後把叢集調整成該 Resource 在 spec 裡面宣告的狀態。例如 Replication Controller 就是會監聽所有叢集內的 ReplicaSet，當有任何 ReplicaSet 被創建、更新、刪除時，把叢集調整成對應的狀態，也就是創出正確數量的 Pods。

因此，如果要讓我們先前創的這個 ChiShengLiu 的 Resource 有作用，我們必須安裝一個 ChiShengLiu 的 Controller 到叢集裡面，這個 Controller 當然沒有內建，必須自己寫，所以叫做 Custom Controller，也稱作 Kubernetes Operator，官方文件稱這個模式為 Operator Pattern。

Kubernetes Operator 最常見的用途是封裝底層邏輯，尤其是框架或工具的開發者，讓使用者可以用 kubectl apply 一個 YAML 檔便可以安裝完畢，其餘的事情 Operator 會幫你處理。

那要怎麼寫 Kubernetes Operator 呢？歡迎關注本系列文的後續更新。

參考資料

• Custom Resources | Kubernetes
• Operator pattern | Kubernetes

有幾個文件是必讀的，這些文件有可能是 .md 檔、.rst 檔、或是網站裡面的某一頁：

• README.md：介紹專案的檔案。
• Contribution Guide：要怎麼貢獻這個專案、提交貢獻時需要遵守哪些格式或規定等。
• Code of Conduct：社群的行為守則，基本上你不要太誇張應該都不會踩到線，但還是要看一下。

Issue Tracker

了解專案使用的是什麼 Issue tracker，常見的有直接用 GitHub issues 或是用 JIRA。新手通常是去找現有的 issue 來解，如果要自己開 issue 的話，務必先搜尋一下有沒有重複的 issue 已經被開過了。

Commits

注意該專案有沒有要求 commit message 的格式，建議養成好習慣，不要亂寫 commit message。如果沒有特別要求，可以參考 Conventional Commits 。基本上格式會像下面這樣：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

範例：

feat: Add XXX feature.

fix(frontend): Fix XXX bugs.

而最常見的 type 有以下幾種：

• feat：增加新功能。
• fix：修 Bug。
• docs：改文件。
• refactor：Refactoring，也就是程式碼邏輯沒有變。
• test：新增或修改測試。
• chore：雜事，不知道怎麼分類就用 chore。

有的專案的符號或是大小寫的格式會不太一樣，例如：

[Feat] Add XXX feature.

[Fix][Frontend] Fix XXX bugs.

另外有的專案會提供 pre-commit hooks，有的話請照著指示安裝。

有的專案會要求每個 commits 都必須被 sign-off，詳細請參考我的另一篇教學 開發開源專案常用的 Git 操作指南 。

Pull Request

如果沒有特殊情形，一個 Pull Request 就是對應一個 issue。基本上要發 Pull Request 前，如果沒有對應的 issue，要先去開一個 issue。但是如果專案沒有強制規定，且你的 Pull Requst 改動的內容也很少，則也可以直接發 Pull Request。

一些特殊用語

有時候 reviewer 會留下一些不常見的縮寫詞或用語，除了自己要看得懂之外，你也可以學著用這些用語，感覺都變專業了😂

• LGTM：Looks good to me。表示 reviewer 覺得你的 code 沒有問題。
• PTAL：Please take a look。請求其他人幫忙 review。
• WIP：Work in progress。表示這個 PR 還沒準備好。
• ditto：「同上」的意思。
• nit：表示 reviewer 建議你修改，但他覺得這不是很重要的修改，所以你可修可不修。例如：nit: Rename this variable to XXX。

身為工程師，Git 可以說是吃飯用的工具， Lazygit 是一個用 Golang 寫的 Git 命令列工具，可以大量節省敲 Git 指令的時間。每次省個幾秒鐘，一年省了好幾個小時。

不要跟我說你敲指令很快（你只是懶得多學新工具），或是用了什麼 alias gs='git status' 之類的化名來幫忙你敲得比較快（你只是覺得學很多快捷鍵很恐怖），相信我，絕對不可能比用這個工具還快。

安裝步驟就不詳述了，請看 官方文件 。

介面

安裝完之後在 Repository 底下執行 lazygit 就可以開啟介面。我設了一個化名 alias lg='lazygit' 幫助我敲得更快。

介面主要分為左半邊和右半邊，左半邊有 5 塊，分別是 Status、Files、Local branches、Commits、Stash，其中某些區塊還有分頁可以切換，例如 Files 那個區塊就還有 Worktrees 和 Submodules 這 2 個分頁。

右半邊有兩塊區域，分別是詳細資訊的預覽，以及每個快捷鍵底下呼叫了什麼對應的 Git 指令。

常用快捷鍵

完整的快捷鍵可以參考 官方文件 。

下面是我最常用的幾個快捷鍵：

• 全域
  • h 和 l：上下切換左半邊的區塊。
  • k 和 j：上下移動光標。
  • /：搜尋字串。
  • [ 和 ]：左右切換左半邊區塊的分頁。
  • Ctrl + o：複製檔名（Files 區塊）、Branch 名稱（Local branches 區塊）、或是 commit hash（commits 區塊）到剪貼簿。
  • q：退出 Lazygit。
• 左半邊 Files 區塊
  • 空白鍵：把該檔案加入或移除自 staging area。
  • a：把全部檔案加入或移除自 staging area。
  • Enter：用在資料夾上為折疊或展開資料夾，用在檔案上則是進入右半邊的檔案預覽區塊。
  • C：打開外部的文字編輯器，讓我們可以編輯 commit message，之後 commit。
  • A：Amend commit。
  • d：取消該檔案還沒有被 commit 的所有變更，注意如果該檔案是新建立的，會被刪除。
  • D：清空所有檔案還沒有被 commit 的所有變更，當你在做功能的時候不小心搞砸了想重來的時候用的。
  • S：打開 stash 選項。
• 左半邊 Local branches 區塊
  • 空白鍵：切換到該 branch。
  • n：從該 branch checkout 出一個新的 branch。
  • f：Fetch 該 branch 在 remote 的新 commits。
  • r：Rebase 到該 branch 上面。
  • R：重新命名 branch。
  • p：Pull 該 branch。
  • P：Push 該 branch。
  • o：開啟 GitHub open pull request 的頁面。
  • Enter：查看該 branch 的 commit。使用 Esc 返回。
• 左半邊 Commits 區塊
  • Enter：查看該 commit 改了哪些檔案。使用 Esc 返回。
  • R：打開外部編輯器更改 commit message。
  • d：刪掉該 commit。
  • g：打開 reset 選項。
  • F：創一個對該 commit 的 fixup! commit。
  • S：Squash 所有在該 commit 之上的 fixup! commits。
• 左半邊 Stash 區塊
  • g：套用並刪除該 stash。
  • 空白鍵：套用但不刪除該 stash。
  • d：刪除該 stash。
• 右半邊預覽區塊
  • v：進入多行選取模式。
  • 空白鍵：把該行，或是多行（用多行選取模式選取的話）加入或移除自 staging area。
  • Esc：回到左半邊的區塊。

實戰

結合一下之前的 開發開源專案常用的 Git 操作指南 這篇文章，講解一下我怎麼用 Lazygit 來開發開源專案。

開新的 Branch

首先當然是要確保 upstream-master 這個 branch 是和 remote 同步的，先用 h 和 l 切換到 Local branches 區塊，然後用 k 和 j 移動到 upstream-master 這個 branch 上面，之後按 f 去抓取最新變更。接著按 n 開一個新的 branch 即可。

同步 Upstream

一樣先移動到 Local branches 區塊的 upstream-master 這個 branch 上面，然後按 f 抓取最新變更，之後按 r rebase 到上面。

開發及開 Pull Request

移動到 Files 區塊，使用空白鍵一個一個把檔案加到 staging area，或使用 a 一次加入所有檔案，然後按 C commit，之後移動到 Local branches 區塊想要 push 的 branch 上面按 P push，最後按 o 開啟 GitHub pull request 的頁面。

結語

一開始你可能會覺得快捷鍵很多很難學，但用久了就會變成肌肉記憶，省下的時間絕對值得。

如果想了解更多的功能，請到官方的 repo 查看。

大家聽到開源專案，第一反應很多應該都是覺得那是技術大佬才能做的。說到要貢獻開源專案，身為學生或是菜鳥工程師，可能會因為沒有接觸過大型專案而感到恐懼；身為資深工程師，也可能會因為怕開發公司內部閉源專案與世界級開源專案所需的實力不同而感到卻步。但實際真的是這樣嗎？或許只是因為沒有人引導你而已。

我的開源經歷

大學的時候，因為學長的介紹而接觸了 Apache Submarine 這個專案，那是我第一次接觸開源，之後也有成功拿到 Committer 的頭銜。至於 Committer 是什麼，等等我會介紹。然而很遺憾我之前沒有寫文章的習慣，所以當時並沒有留下任何心得文。這次很高興被提名為 Flyte 的 Committer，因此來留下一篇文章當作心得紀錄。最近我也有在貢獻 KubeRay 這個專案，或許有機會之後我會另外寫一篇文章，完整介紹我的開源之旅，也把以前沒有紀錄下成為 Apache Submarine Committer 的心得補上。

Flyte 專案介紹

Flyte 是一個管理 workflow 的工具，基本上就是另一個很有名的專案 Apache Airflow 的競品。強調比 Airflow 更高的 scalability。背後的商業公司是 Union.ai 。大家不要看到開源專案背後有商業公司就覺得很奇怪，事實上幾乎所有開源專案背後都有企業在支持。

Committer 是什麼

當你想要貢獻一個開源專案，你一定不可能對 Repository 有寫入的權限，所有貢獻都是以 Pull Requests 的形式提交，必須由專案的維護者合併你的 Pull Requests，這時你會被稱為 Contributor（貢獻者）。

當你的貢獻達到一個程度，受到專案維護者的青睞時，這時就有機會被邀請加入組織，成為 Committer（不同專案的術語可能不同），這個我不知道中文翻譯叫做什麼，不過大概就等同於「核心貢獻者」。此時你對 Repository 就會有直接寫入的權限，也可以幫忙合併其他 Contributor 的 Pull Requests 了。

參與貢獻 Flyte 的過程

今年 1 月的時候，因為 許秉倫 學長從美國回來的一個飯局的一次機遇，加上後續與許多前輩包括 蔡嘉平 、 莊偉赳 職涯諮詢的關係，我決定辭掉現有的工作，一邊做開源專案，一邊申請美國研究所。做開源專案除了你的程式碼可以被很多人使用，獲得成就感之外，還有比較現實的一點就是可以幫履歷添光。為了之後去美國找工作順利以及一些其他因素，我決定重新回來做開源（正如我之前所說，我並不是第一次貢獻開源專案）。

從 2 月開始我加入了 源來適你 這個開源社群，這個社群非常特別，不同於其他台灣的開源社群，源來適你裡面有許多導師帶你實際貢獻開源專案，而 Flyte 這個專案的導師主要是 蘇桓平 (Kevin) ，其實這不是我第一次認識他，因為他是 Apache Submarine 的 PMC Member，也就是說我以前貢獻 Apache Submarine 的時候他也是我的導師之一。

稍微扣回標題，為什麼說我是「透過源來適你」成為了核心貢獻者呢？主要就是因為源來適你的導師群的原因。正如我前面所提到的，大多數人對貢獻開源專案感到恐懼，最主要的原因其實就是不了解開源生態系。如果有個好的導師帶領你的話，貢獻的難度就會遽降。

無論你是學生、菜鳥工程師、資深工程師，卻步於貢獻開源專案，不外乎是因為覺得專案很複雜、技術門檻很高。而導師的存在，可以找出許多非常簡單好上手的題目給你做，甚至還可以讓你問問題、手把手教學等。相較於自己在茫茫大海的程式碼、issue 之間摸索，有個導師可謂是事半功倍。任何專案一定都會有比較簡單的任務需要人去做，所以完全不用怕自己的實力不夠導致完全不知道怎麼下手。另外導師還有一個最重要的任務：幫你合併程式碼。通常你自己提交了一個 Pull Request 到一個稍微大一點的陌生的專案，你會有 99% 以上的機率等了一個月都沒有人回覆你，而導師通常就是專案的核心貢獻者，具有合併程式碼的權限，因此你不會提交了程式碼卻石沉大海。這對於新手是很重要的，想像你一直被不讀不回，你會不會感到焦慮？會不會信心受到打擊？這也是許多人無法持之以恆貢獻一個開源專案的原因。

從 2 月開始我便著手貢獻 Flyte 這個專案，很高興秉倫學長分給我一些 FlyteInteractive 的東西做，讓我的名字可以出現在 Linkedin 的 Blog 上面。

在 2~7 月期間我提交了 38 個大大小小的 Pull Requests，8 月時很高興被已經在 Union.ai 工作的 陳翰儒 提名為 Committer 。

其實比起其他更大型的專案，這個數量算很少，我在這期間是一邊準備申請研究所的東西，主要是托福，這也代表其實 Flyte 這個專案成為 Committer 的門檻不算很高，因此非常適合開源新手前來貢獻。

源來適你詳細介紹

源來適你（OpenSource4You） 是由 蔡嘉平 創立的一個台灣的民間開源社群，蔡嘉平本身是 Apache Member，也是 Apache HBase、Apache Kafka、Apache YuniKorn 專案的 PMC Member。除了蔡嘉平本人之外，社群內目前還有其他數位導師分別帶領大家參與貢獻不同的專案，例如 陳楷訓 、 蘇桓平 、 許秉倫 、 陳昱霖 、 劉勛 、 李唯 等。相較於其他台灣的開源社群，真正動手實作的比例更高。在導師們的指導之下已有數位社群成員成功斬獲各個專案的 Committer 頭銜。

截至目前源來適你的活動包含：

1. 每個開源專案小組的每週例行會議，在撰文的當下有 6 個專案小組在同時進行中。
2. 每星期三晚上的讀書會，大家一起學習新知。
3. 每星期六的演講，邀請台灣和美國矽谷的業界人士來分享，主題橫跨技術、職涯、八卦、管理、教育等各種和開源軟體有關的話題。
4. 不定期的線下活動，讓大家面對面認識一下。
5. 補助表現優異的成員開發設備或是活動經費。
6. 出席各種軟體大會當講者，例如之前分享的 Apache CommunityOverCode ，以及在台灣舉辦的 COSCUP，都有社群成員去演講。

致謝

• 感謝 嘉平 ，創辦了源來適你這麼棒的組織，這幾個月以來參加社群大大小小的活動、在 Slack 裡面和大家講幹話，真的非常充實且開心。除此之外你還提供了我生涯諮詢以及經濟援助，你真的是我非常尊敬的人，非常感謝！
• 感謝 桓平 (Kevin) ，不管是以前的 Submarine，還是現在的 Flyte，你真的是個很好的導師，對於這兩個專案感覺我問什麼你都知道，完全沒有你不會的問題。希望你之後職涯順利，之後去美國再去找你碰面！
• 感謝 翰儒 ，從來沒有看過這麼熱血的做開源的大學生，比我以前第一次做 Submarine 還認真，也感謝你一直幫我跑 CI 和提名我為 Committer。祝你早日被 relocate 到美國，薪資 up up up。
• 感謝 秉倫 (Byron) ，以前大學是你找我進資訊部的，Submarine 是追隨你才開始做的，這次做 Flyte 也是你從美國回來之後找你吃飯的飯局聊天聊出來的機遇，你甚至還丟了一些很簡單的 FlyteInteractive 的事情給我做，讓我的名字可以被放在 Linkedin 的 Blog 上面。你絕對是我從大一以來就認識的最罩的學長，沒有之一。
• 感謝 Jason ，在你那邊學到了一些 Flyte 在 Line 公司內部的應用，和你聊天也很愉快，希望之後還有機會交流！
• 感謝 Troy ，雖然我們比較沒有在程式碼上面合作到，但是感謝你在 Slack 裡面指點了我一些準備申請研究所的問題。希望你之後在 Union.ai 過得順利！
• 感謝 立行 (Austin) ，成為一起申請今年研究所和一起做 Flyte 的戰友，你跟我這幾個月做的事實在非常像，有種好像是同學的感覺，畢竟我同學幾乎都已經先去美國了，有戰友肯定是比孤軍奮戰好，希望我們都能順利申請到好學校！

最後感謝 源來適你 的各位導師和成員，也歡迎大家加入這個大家庭！

相關連結

• 源來適你

  • Facebook 粉絲專頁

  • 訂閱行事曆

  • 加入 Slack 頻道

• 其他社群成員的 Flyte 相關文章

  • 如何成為 Open Source Committer (Flyte) | 大學生 21 周心得分享 - Han-Ju Chen
  • 普通人也能做到的 Open Source 開源一年 100+ PRs 完整指南 feat. 源來適你, Flyte - Han-Ju Chen
  • 開源入門到加入夢幻新創！- Troy Chiu
  • Flyte 開源之旅 — 從開始到現在 - Jason Lai
  • Open Sourcing FlyteInteractive: Saving thousands of AI engineering hours in developing ML interactively | Linkedin Engineering Blog - Byron (Pin-Lun) Hsu

要開發開源專案首先必須先 Fork Repository ，因為不是自己的專案，我們沒有寫入權限。

Fork 完之後會有一個一模一樣的 Repository 出現在自己的帳號底下，我們通常把原本的專案叫做 upstream repo，自己 fork 過來的叫做 downstream repo。

自己 fork 過來的 Repository 我們就有寫入權限了，首先先把他 clone 下來 ，注意是 clone 自己 fork 過來的 repo，不是 upstream repo 。

假設我們要貢獻 kuberay 這個專案，而自己的 GitHub 名稱叫做 MortalHappiness，那麼 upstream repo 的 URL 會是 https://github.com/ray-project/kuberay.git，而自己 fork 出來的 repo URL 應該會是 git@github.com:MortalHappiness/kuberay.git（SSH）或是 https://github.com/MortalHappiness/kuberay.git（HTTPS）。假設我們使用 SSH。

Clone 下來之後可以執行 git remote -v，應該會長得像下面這樣：

origin  git@github.com:MortalHappiness/kuberay.git (fetch)
origin  git@github.com:MortalHappiness/kuberay.git (push)

接著需要添加 upstream remote，執行以下指令：

1
2

git remote add upstream https://github.com/ray-project/kuberay.git
git remote set-url --push upstream no_push

上面的指令第 1 行的 URL 要換成想貢獻的專案的 upstream URL。第 2 行則是避免我們不小心 push 到 upstream repo 上面。（其實我們也沒有寫入權限，本來就不能 push，但是說不定有一天我們做得很好，變成了 Committer 之後就有寫入權限了，加上這行可以避免我們不小心 push 到 upstream。

再次執行 git remote -v 應該會像下面這樣：

origin  git@github.com:MortalHappiness/kuberay.git (fetch)
origin  git@github.com:MortalHappiness/kuberay.git (push)
upstream        https://github.com/ray-project/kuberay.git (fetch)
upstream        no_push (push)

接下來下面這個是我個人的習慣，不一定需要這樣，為了避免不小心在 master branch（或 main branch）上面開發功能，我會創一個 local branch 去 track upstream/master branch，然後把 local 的 master branch 砍掉。

1
2
3

git fetch upstream
git checkout -b upstream-master upstream/master
git branch -d master

如果有在用 GitHub CLI ，可以順便把 default repo 設成 upstream。

1

gh repo set-default https://github.com/ray-project/kuberay.git

上面指令的 URL 記得換成自己的 upstream URL。

開發新功能流程

1. 確保 local 的 upstream-master branch 和 remote 是同步的：

   1 2	git checkout upstream-master git pull upstream master

2. Checkout 出新的 branch，假設叫做 feature/example：

   1	git checkout -b feature/example upstream-master

3. 正常開發（add、commit、push）。

4. 去 upstream repo 開 pull request 。

同步 Upstream

假設開發到一半，upstream repo 有新的 commits，這時就需要同步 upstream，執行 git pull upstream master。

Sign-off Commits (DCO)

有些開源專案會要求每個 commit 都必須被 sign-off，沒有做的話 CI 有個叫做 DCO (Developer Certificate of Origin) 的會 fail。sign-off 的步驟很簡單，就是在執行 git commit 的時候加上 -s 的 flag，變成 git commit -s。效果是會在 commit message 的最後加上一行 Sign-off-by。所以 commit message 會變得像下面這樣：

Some commit message.

Signed-off-by: Chi-Sheng Liu <chishengliu@chishengliu.com>

注意這邊的 sign-off 和 GPG-signed commits 是不一樣的。

如果 commit 的時候忘記加上 -s 的 flag，可以參考 這個連結 去補救。

如果覺得每次都要加 -s 這個 flag 很麻煩，可以使用 commit-msg hook：

View this GitHub Gist

把上面的內容寫到 .git/hooks/commit-msg 裡面，然後執行 chmod +x .git/hooks/commit-msg 即可。

今年很高興能以志工的身份參與在杭州舉辦的年度開源軟體大會 Apache CommunityOverCode 亞洲場。此外本次台灣開源社群「 源來適你 」也有社群成員以講者和一般參與者的身份一同前往此次盛會。所以這次我（劉奇聖）和源來適你的另一位成員 劉立行 來一起寫一篇遊記，介紹這場國際開源軟體大會的細節與我們的收穫，以及「源來適你」這個台灣開源社群。

什麼是 Apache 軟體基金會？

Apache 軟體基金會（Apache Software Foundation, ASF）是目前全世界最大的開源軟體組織，由世界各地的開發者所組成，其組織下的軟體遵循 Apache License ，孕育了 Hadoop、Spark、Kafka、Flink 等許多知名專案。

什麼是 Apache CommunityOverCode？

Apache CommunityOverCode，舊稱 ApacheCon，是每年都會舉辦的屬於 Apache 軟體基金會的開源軟體大會，分為亞洲場、歐洲場、北美場。經過一次重新命名，強調「 健康的社群比好的程式碼更重要 」。今年我們參加的是在杭州舉辦的亞洲場。

為什麼要參加 Apache CommunityOverCode，而且是參加實體場而不是線上直播？

參加現場活動有幾個顯而易見的理由：

• 人脈：到現場參加有機會認識更多的朋友或是講者，建立人脈，幫助之後職涯發展。
• 臨場感：體驗國際級軟體大會現場的氛圍。
• 提問的機會：在現場才有機會向講者提問與討論，線上參加的話無法提問。
• 觀光：到現場可以順便到當地的旅遊景點觀光。
• 網友見面會：跟一同開發過開源專案，卻因地理原因沒有實體碰面過的夥伴們面對面交流。

如何實體參加 Apache CommunityOverCode?

基本上有 3 種管道：一般買票報名、報名當講者、申請當志工。下圖是註冊頁面。

• 一般買票報名：一般買票報名是需要報名費的，若為 Committer 身份（擁有 Apache 信箱，有興趣的話文末會介紹 Apache 專案的角色結構說明如何取得這個身份）可以打折，另外學生和目前無業的人可以申請免費門票，但需要審核。
• 報名當講者：報名當講者如果被接受可以獲得免費的講者票，此外講者還可以發公關票給親朋好友，讓他們獲得免費的票來一起參加。
• 申請當志工（劉奇聖）： Apache Travel Assistance Committee (TAC) 是 Apache 用來補助想參加 Apache 的活動但經濟不是特別富裕的人的一個委員會，我們可以在他們的官網申請當志工，注意不用是 Committer 也可以申請！Committer 可以直接用 Apache 的信箱登入，非 Committer 則可以註冊帳號，但經過源來適你社群成員實測，Gmail 好像有時候會收不到信，Outlook 則比較容易收到信，如果收不到信可以換一個 Email 試試看。申請通過之後 TAC 會補助你機票、住宿、大會入場的票券等費用。可以省下不少支出，非常推薦大家申請志工（當講者只有免費的票，機票和住宿還是要自己買，相比之下志工真的省超多）。
  • Q: 志工可以省多少費用？
  • A:
    • 機票：原本直飛是 £313 GBP，這次剛好遇到颱風改成轉機的班機，變成 £1188 GBP。另外我是從桃園國際機場（TPE）飛到杭州蕭山國際機場（HGH）而已，這次有位志工小夥伴是從英國來的，機票可以省更多錢。
    • 入場費：Committer ￥799 CNY、非 Committer ￥1,099 CNY
    • 住宿費：4 晚約 $8000~$10000 TWD
    • 總和：依我的情形來說，省了 £1188 GBP + ￥799 CNY + $8000~$10000 TWD = 約 $62000 TWD

什麼都不懂的小白適合參加嗎？（劉立行）

先講結論：「肯定適合！」

Apache 軟體基金會囊括形形色色的項目，每位與會的講者都有各自擅長的領域，他們也會儘量以白話的方式把講題說清楚，所以不太需要擔心對特定項目技術細節不熟悉而聽不懂。

建議小白參加者可以在會前先做點功課，先針對時程表挑出較不會涉及特定項目技術細節的議程：例如一些議題在討論如何提升效能或減少資源用量，這類跨項目都通用的優化手段、技巧，就很適合小白利用有限的領域知識加上本身的技術直覺參與聆聽。

舉例來說，「Exploration and Practice of Flink SQL Performance Optimization at ByteDance」這場由字節跳動工程師主講其公司內部對 Flink SQL 的種種優化，你可以稍微了解 Flink 在做什麼、為了解決什麼問題而生等。但不需要真的很熟悉 Flink 的 codebase 與大部分的技術細節，也能夠聽懂他們的優化的切入點，有一些通用的優化技巧，可以套用到其他專案，例如 Caching、SIMD Vectorization、Space/Time Trade-off 等；而另一場由 Cloudera 產品經理主講的「Navigating the Lakehouse with Confidence: Best Practices for Implementation with Apache Iceberg」，雖然主軸在分享他們客戶使用 Iceberg 的最佳實踐，但資源成本、效能提升等議題也總離不開 Partition、Data Compaction 等發力點。

總而言之相當推薦各位讀者參加，若有參與這種國際級的技術大會的機會，一定要把握！真的太值回票價了。

部份議程聆聽心得

議程主要分為兩部份：Keynotes 和 Guest Speakers。Keynotes 的主題通常會比較廣泛，切合大會主題並激起大家興趣等。Guest Speakers 則是由社群的人投稿，對於某個專案或領域做深入的介紹和探討。上午的議程都是 Keynotes，地點在主會議室，下午則是 Guest Speakers，分散在各個會議室，大家可以自己挑有興趣的主題聆聽。

Keynotes 通常是 1~2 個講者在講一個主題，但裡面也有比較特殊的部份，例如 4～5 個人坐在台上聊天談論某個主題的圓桌會議，以及每個人限時 5 分鐘講一個主題的 Lightning Talk。

下圖是大會第一天的行程，大家可以感受一下。為避免佔用太多版面，第二天和第三天的行程就不詳細放上來了。

Keynotes

Opportunities and Challenges of Globalization - Xu Wang, Junping Du, William Guo, Zili Chen

劉奇聖：

這個圓桌會議討論了許多開源和國際化的問題，我覺得非常有趣。

開源社群本地化和國際化語言上的矛盾

有一點提到開源社群的語言問題，想要國際化勢必需要英文的文檔，否則會把貢獻者的來源限縮在本地。但是如果最後的市場是本地的市場，則可能也需要使用本地的語言，不然若有競品而且競品的文檔是使用本地語言，則很可能完全無法與之競爭。但是同時維護多語言的文檔是一件非常累的事，一來不是所有開發者都精通各種語言，二來同時具有多語言文檔的時候，若某個段落需要更改，則需要更改多個地方，容易導致不同語言文檔之間資訊不同步的問題。因此如果需要專案需要國際化，通常還是以只維護一份英文文檔為主。

地區偏好差異形成專案推廣的絆腳石

另一個問題是 Product Market Fit（PMF）的問題，一個在某地區非常盛行的專案，想要推廣到不同地區時，有可能因為該地區的使用習慣與其他地區不同，導致無人問津。一位講者提到他曾參與過一個專案，使用 Drag-and-drop 的 No-code 的方式建立 workflow，在亞洲非常盛行，但是想推廣到歐美市場時發現該地區的人習慣使用寫程式的方式建立 workflow，所以推廣得非常不順利。

不同地區開發氛圍與價值觀的磨合

還有一個有趣的議題是不同地區的開發氛圍問題，一位講者提到對於歐美開發者來說，使用郵件溝通，回覆時長可能超過一天以上，大家可能覺得沒什麼問題，但是對於華人來說，開發氛圍屬於比較「卷」，所以很多人都期望訊息能在幾十分鐘之內被回覆，這會導致除了面對國際的溝通軟體之外，如果最後產品想推往華人市場，可能還需要使用不同的溝通軟體創建一個面對華人開發者及用戶的頻道，增加維護的困難性。一位講者提到一個觀點，我認為非常值得我們反思，也就是「一時慢不代表長久會慢」，回覆慢可以讓開發者們仔細審視程式碼的品質，降低之後發生問題的機率，若每次都追求快速合併程式碼而不經仔細思考，可能在未來付出需要一直修補漏洞的代價，反而拖慢整體速度。此外做一件事情慢也不代表整體會慢，因為國際化的開源專案會有很多公司參與其中開發不同功能，可能一個功能會做得很慢，但同時間會有很多個功能在開發中，因此把時間拉長來看，整體速度其實是會非常快的。

Open Source: how we got here, where we’re going - Bruce Perens

劉奇聖：

這位講者非常厲害，是「開源定義」的主要作者，現在該定義變成美國法院裁決一個軟體是否為開源的基準。他也是 BusyBox 的作者以及第二任 Debian Linux 項目的負責人。

開源的歷史及現在的挑戰

講者首先講述了開源的歷史，接著提到了目前開源的困境，包括現在世界上多數大公司都在用著各種開源專案，但這些開源專案維護者很多都是用愛發電做功德，大公司並沒有付錢給這些人，當開源專案維護者一個人用愛發電無法做完全部的事情的時候，難免會開權限給其他貢獻者讓他們有提交程式碼的機會，如果這時這些貢獻者裡面有惡意的人，就會發生大災難，例如前陣子鬧得沸沸揚揚的 xz 後門事件 。另一個困境是現在的開源 License 實在太多，大公司每年需要花許多錢去確保程式碼符合這些 License。

「後開源」：拒絕讓大公司再當免費仔，該付錢啦！

講者針對上述困境提出了一個倡議，叫做「 後開源（Post Open） 」，概念是對於個人和小公司，開源軟體依舊保持免費，但是對於年收入超過五百萬美元的大公司，若要使用開源軟體則需付一部分的錢給開源社群，這些錢會依照開發者的貢獻程度以及每個開發者的貢獻分別有多少公司正在使用去做分配。

個人對「後開源」的看法

我認為講者提出的這個概念是個非常美好的願景，能夠給開源專案維護者不小的動力，畢竟人也不能一直用愛發電和做功德，熱情總會有耗盡的一天，大家都會有 burn out 的時候，對於先前默默貢獻的偉大開源貢獻者們，我一直都是對他們有著最崇高的敬意。這個倡議要推行一定也會遇到許多困難，但講者在幾十年前都能成功將開源變成美國法院裁決基準，我相信講者想要推動的這個願景肯定也不是完全不可能的事，希望他會成功！

劉立行

奇聖上述心得大致描述了 Bruce Perens（Busybox 的作者）的分享：Bruce 對 Post Open Source 時代的期許與願景，值得一提的是他表示透過開源，企業得以共享基礎設施的開發維護成本，專注在自家商業產品的差異化，然而全世界最重要的幾個關鍵基礎軟體設施，往往都由一兩位自願貢獻者無償維護，對整個生態系是很不健康的，Post Open Source 希望在未來建立健康的開源盈利模式，解決複雜的授權問題，他也表示這很有野心極巨挑戰，但仍認為值得一試。

這位滿頭白髮的 66 歲講者雖然也因颱風班機取消，只能預錄影片，依然仍能感受到他充滿活力貢獻社群。

我個人認為這已經是開源生態系長年的文化了，要突然發生質變的難度頗高，但也很樂見這種倡議把開源世界推向更不投機、更健康的路上，我也非常期待「 後開源（Post Open） 」之後的發展。

Toward a Sustainable ASF Community: The Power of Cross-Cultural Understanding and Consensus - Willem Jiang, Richard Sikang Bian

劉立行：

開源如戲，透過一場小品瞭解開源社群的衝突與因應之道

來自螞蟻集團和字節跳動的工程師透過話劇的方式演示開源組織裡的工程師們工作的日常，溝通之間的摩擦、文化衝突對立以及如何達成共識，這場分享以活潑生動的方式呈現，吸引了台下觀眾的們眼光，娛樂效果十足。

雖說是演戲，不過這些衝突、誤會的場景對於投入開源世界的工程師們個該不算陌生，甚至是每天上演的。兩位講者巧妙地透果旁觀者清的話劇模式拋出這些議題讓大家思考，發人省思：code review 時應該給足 context、不要替對方預設立場、還要考量到彼此的 unknown unknowns，希冀我們都能成為更優秀的工程師，為世界增添一份美好。

Guest Speakers

State of Apache YuniKorn - Yu-Lin Chen, Chia-Ping Tsai, Kuan Po Tseng, TingYao Huang, PoAn Yang

劉奇聖：

從小白到成為國際級軟體大會講者

這個演講比較特別，是由我們「 源來適你 」的社群成員組了一隊 YuniKorn 小隊投稿當講者。 Apache YuniKorn 是 Kubernetes 原生 Scheduler 的一個替代品，實現了更多進階的功能，目前在 Apple 內部被大量使用。這個演講簡單介紹了 YuniKorn 的基本功能、最新版本已經實現的新功能、現在社群的狀態以及正在實做的功能等。聽完這個演講我最大的感觸是源來適你真的是一個很棒的組織，雖然我沒有參加 YuniKorn 的開發，但知道這些講者有些人一開始也是完全沒有接觸過開源專案的小白，而在社群裡面導師的指導之下，成功獲得 Committer 頭銜，甚至還一起組隊前往國際級的軟體大會給演講。部份成員在取得頭銜之後也不會消聲匿跡，例如昱霖（Yu-Lin）在成為 committer 後仍繼續提攜後輩回饋社群，而廷堯（TingYao）則在忙碌的工作下依然會抽空以 PMC Member 的視角陪大家討論技術。

劉立行：

沒錯，這場分享十分特別，由各自來自不同公司的一群熱情工程師們帶來他們對 YuniKorn 社群近況的更新。

YuniKorn 是一款 Kubernetes scheduler，提供了原生 scheduler 沒有的 gang scheduling 的能力，也就是在進行資源排程時，能做到 all or nothing，這對於現代 AI workload 是很重要的，舉個例子：假設 distributed model training data parallelism 需要用到 10 個 K8s Pods，每代算完要把參數全部 sync 後才更新傳回去給 10 個 Pods，這正是需要用到 gang scheduler 的時機，此外 YuniKorn 也支援 Multi-tenancy，可以設定各 Queue 用到各種資源的 Quota， Multi-tenancy 對現代雲端服務可說是不可或缺的需求，YuniKorn 更提供 Preemption fence，讓同叢集內不同組織的資源不會在排程時被彼此影響或搶用。

YuniKorn 台灣戰隊的成員們，各自不辭平日白天工作辛勞，晚上假日無薪投身開源貢獻程式碼、解 bug，鍛鍊自我工程能力，為履歷鍍金再鍍金，這種情操相當偉大也令人佩服，非常歡迎大家一同加入 YuniKorn 台灣戰隊的行列，成為一位 10 倍工程師。

The Evolution of Data Infrastructure in the Age of LLM - Xun Liu

劉奇聖：

大型網友見面會？透過本次大會與過往開源前輩見面交流

這個演講是 Xun Liu （劉勛，我們都稱呼他為勛哥）主講，他現在是新創公司 Datastrato 的 COO，其主要產品是 Gravitino ，目前已經捐獻給 Apache 基金會，這次演講介紹了 Gravitino 在 LLM 時代的應用。勛哥之前是 Apache Submarine 的 PMC Member，在我以前還是個開源小白，開發 Apache Submarine 時給了我許多幫助，也是他提名我成為 Apache Submarine Committer 的。從前我們都只在線上開會的時候見面，這次非常高興有機會能有實體碰面的機會。我想這也是這種開源大會的一個目的：大型網友見面會。開源專案通常都是一群志願者遠端開發，甚至有可能在地理上跨越了非常遠的距離，很難有實體見面交流的機會。而開源軟體大會充當了一個媒介，讓開發者們可以面對面交流。這次勛哥還當了杭州在地嚮導，帶我們到處吃喝玩樂，非常感謝他的幫忙！也歡迎大家加入源來適你 Slack 裡的 #apache-gravitino 頻道，讓勛哥帶領你一起開發 Gravitino，有機會成為 Committer，獲得酷炫 Apache 信箱，為履歷添光！

劉立行：

Xun Liu 是 Datastrato 的共同創辦人，他們公司最近將旗下項目 Gravitino 捐給 Apache 基金會，Gravitino 提供統一 metadata 的管理方案，適逢 Tabular 併購案掀起的波瀾未平，Gravitino 在 metadata 領域可說是完美鎖定了下一個技術熱點，在兵家必爭之地洞燭機先。

在這場 Gravitino 與 AI 分享，其中特別提到一個大 feature Issue #4104 ，示範了統一 metadata 在大型 dataset 管理中扮演的角色，確實很有趣。

Gravitino REST catalog service for Apache Iceberg, why and beyond - Xiaojing Fang

劉立行：

優化再優化，給我最好用的 Iceberg Catalog

Xiaojing 也是來自 Datastrato 的軟體工程師，這場演講分享了 Gravitino 如何引入整合了 Apache Iceberg REST catalog 客戶端，提到了當前 Iceberg catalog 的侷限：

1. 不完善的語言與環境相容性
2. 像 Hive lock 一樣的效能極限
3. 為了保證不同 catalogs 一致性所造成的複雜性
4. 除錯、監控、審核的難度較高。

Gravitino 嘗試透過建立可插拔的 Iceberg REST catalog 系統進而降低維護雜度、提升效能與與提供更高的安全性。

其中特別有趣的一點是，小客戶端大伺服端的設計決策，把整個系統中不少元件都移到伺服端，所以整個架構的 design space 又更大了，能操作的事更多，能加入的優化機制也更多元，例如在伺服端實作 metadata caching，顯著的提升了效能。

我在 2024 年初有貢獻了一點點 PR 到 Gravitino，Datastrato 的工程師們都非常有效率且有能量，大家的回饋都非常即時且有建設性，開會的強度也都很高，身為 Apache 基金會的董事會成員和 VP Incubator 的 Justin Mclean 也是 Datastrato 的成員之一，大會期間也時常能見到他到處和大家聊天的身影，Justin 甚至有來 review 過我的 PR! 總之有興趣的夥伴千萬不要錯過下個焦點技術 Gravitino ，開源的好處就是程式碼都是公開的，各位不妨來看看程式碼一探究竟，說不定能順手貢獻幾隻 PR。

其他

劉奇聖：

演講太多眼花撩亂？要怎麼挑選適合自己聆聽的主題？

由於 Guest Speakers 的演講實在太多，因此剩下的就在這邊挑幾個簡單講一下心得。沒有人是什麼領域都精通的，因此聽演講時聽不懂非常正常，這時就可以挑和自己會的東西比較相近的主題去聆聽。「The best pratice of integration technology driven by event in cloud - 晓慧 武, Alan Liu」是由 RedHat 的工程師來講 Kubernetes 和 microservices 相關的東西，由於我之前在開源專案裡很常寫 Kubernetes Operator，因此這個演講就比較聽得懂。另外也可以挑一些非技術的演講去聽，例如「Developing Soft Skills for a successful Open Source career - Sumaiya Nalukwago」。當然也可以聽當前非常熱門的技術主題，例如由 Cloudera 的人講的「Navigating the Lakehouse with Confidence: Best Practices for Implementation with Apache - Bill Zhang」，探討了 Apache Iceberg 的一些議題，我覺得非常的有深度。

志工心得（劉奇聖）

歡迎會晚餐聚餐

Day 0 活動都還沒開始的時候，旅遊補助委員會的成員就邀請志工們一起到一家叫做「乾塘大院」的餐廳聚餐，很意外的志工裡面的亞洲人只有包含我在內的 3 位華人和 4 位印度人，沒有亞洲的其他地區的人，我原本以為亞洲場可能會有像是日本、韓國之類的亞洲人。其他志工幾乎都是母語為英文的人，加上印度人的母語也是英文，另外兩位華人的英文也非常溜，然後就發現尷尬了，我的破英文好像沒辦法跟上大家的尬聊內容，只能偶爾回個幾句加上陪笑🥲

不過大家人都非常 nice，氣氛非常融洽，經過這次教訓我深刻認知到英文的重要性，之後我會好好學習英文的。

工作內容

其實志工的工作並沒有很多，只需要在 3 天內選一個 2 小時的時段坐在 Apache 的貼紙桌前面（上圖），有人經過的時候跟他們說貼紙隨便拿就可以了，因為太無聊了，所以我就順便把亂七八糟的貼紙堆分類了一下，就像上圖那樣。

此外還要選一天到註冊桌那邊幫忙處理註冊的東西，但是後來發現註冊桌已經有本地的工作人員了，因此我根本就不用做事，坐在旁邊當花瓶就好了😂

最後是統計有去聽的 Guest Speaker 的場次的聽眾有多少，回報給大會，方便大會了解哪些 Guest Speaker 的主題是比較多人聽的，這項工作也是非常輕鬆，數人頭而已。

證書

活動結束後志工還會收到一張精美的裱框證書，感覺放在 LinkedIn 或是申請研究所的履歷上面都非常不錯！志工好處多多，非常推薦大家報名當志工！

杭州浙大森林會場周邊環境與交通

這次會場座落於杭州浙江大學紫金港校區，距離機場車程約 1 小時，不算市中心，但腹地廣大，下圖為校園一隅。

離開校區外交通移動上使用當地的網約車（例如滴滴出行）還算方便，街道上以及我們搭乘的幾乎全是電動車。

手機應用程式方面，計程車主要就是滴滴，食物外送主要就是美團，行動支付則有支付寶（alipay）以及微信支付，而阿里巴巴集團總部正位於杭州，整個城市數位化相當普及，建議如果未來有讀者參加在中國舉辦的 Apache CommunityOverCode，可以先安裝當地的 App 熟悉一下。

會外行程（劉立行）

原訂的出發日我們不幸遇到颱風攪局，發生全員班機被取消的插曲，但大風大雨仍澆不息我們的熱情，甚至大會志工的奇聖在停班日天未亮一大早就先到香港等待轉機。

我們一行人從台灣抵達杭州當晚，身為杭州在地人的勛哥立馬在中國知名連鎖串燒店「木屋燒烤」設接風宴招待我們嚐嚐鮮。

大夥們痛飲著啤酒、大口啃著串燒，一群技術 nerd 在酒酣耳熱之際也不忘討論技術、開源專案的社群文化治理、開源與商業間的策略權衡等議題，勛哥舉了 Docker 背後的公司為例：即使做出了技術很強、用戶非常多的產品，但太開放到用戶都能輕易自行 fork，在商業上也不一定是成功賺錢的，所以開源專案在生命週期各階段該採用的策略與方向都是需要經過縝密的規劃。

很幸運透過這場活動外的飯局，讓我近距離一窺行業技術領先者的思維與視角，可說是最珍貴的收穫。

第二天團員們在下午的議程結束後，迫不及待相約坐車到西湖遊覽名勝美景，當個觀光客，路上有說有笑，晚上勛哥則帶我們到湖邊的餐廳大快朵頤一頓。

最後一晚則發生了許多神奇的事情，在此就不透露了，有興趣的讀者歡迎加入源來適你社群瞭解詳情。

Apache 基金會專案角色詳細介紹（劉奇聖）

講了這麼多，對 Apache 基金會這個世界最大的開源軟體組織有興趣了嗎？也想取得酷炫的頭銜放在履歷上？這裡來介紹一下 Apache 專案的角色結構。

根據官方網頁 ，每個 Apache 專案通常都會有以下幾種角色：

• User：使用該專案的軟體，不參與開發。
• Developer (Contributor)：參與開發專案的人，但對專案的 repository 無寫入權限。
• Committer：當參與開發專案的貢獻達到一個程度之後，PMC 們可能會提名你為 Committer，此時會有對該專案的 repository 寫入的權限，同時如果你還沒有一個 Apache 的信箱的話會獲得一個。例如我的信箱是 chishengliu@apache.org
• PMC Member：當參與專案更久之後可能會被提名為 PMC Member，此時會獲得決定該專案長期走向、提名活躍 Contributor 成為 Committer 等權力，另外需要在專案有正式的 release 的時候進行投票。
• PMC Chair：PMC Chair 是 PMC Member 之中的老大，負責跟董事會溝通，還有一些額外的職責。
• ASF Member：當成為了多個專案的 PMC Member 之後，有機會被提名為 ASF Member，擁有成為董事會的選舉人、被選舉人的權力，以及孵化新的專案等。

擁有 Apache 信箱除了看起來非常酷炫之外，也有些其他附帶的好處喔！例如 JetBrains 全套 IDE 的免費使用 ！

源來適你是怎樣的組織？

源來適你（OpenSource4You） 是由 蔡嘉平 （左邊數來第三個，穿花襯衫的那位）創立的一個台灣的民間開源社群，蔡嘉平本身是 Apache Member，也是 Apache HBase、Apache Kafka、Apache YuniKorn 專案的 PMC Member。除了蔡嘉平本人之外，社群內目前還有其他數位導師分別帶領大家參與貢獻不同的專案，例如 陳楷訓 、 蘇桓平 、 許秉倫 、 陳昱霖 、 劉勛 、 李唯 等。相較於其他台灣的開源社群，真正動手實作的比例更高。在導師們的指導之下已有數位社群成員成功斬獲各個專案的 Committer 頭銜。

截至目前源來適你的活動包含：

1. 每個開源專案小組的每週例行會議，在撰文的當下有 6 個專案小組在同時進行中。
2. 每星期三晚上的讀書會，大家一起學習新知。
3. 每星期六的演講，邀請台灣和美國矽谷的業界人士來分享，主題橫跨技術、職涯、八卦、管理、教育等各種和開源軟體有關的話題。
4. 不定期的線下活動，讓大家面對面認識一下。
5. 補助表現優異的成員，例如本次的 Apache CommunityOverCode 亞洲場就有部份社群成員獲得補助，得以參加此次國際級的大會增廣見聞。
6. 出席各種軟體大會當講者，例如這次 Apache CommunityOverCode 的 YuniKorn 講者群，以及近期在台灣舉辦的 COSCUP 都有社群成員去演講。

非常歡迎大家看完這篇文章之後可以到 Facebook 粉絲專頁按讚 、 訂閱我們的行事曆 、並 加入我們的 Slack 頻道 一起聊天！

結語

本次參與 2024 Apache CommunityOverCode 亞洲場是一次非常難得的經驗，真的非常推薦大家不管是學生還是資深軟體工程師都至少參加一次這種國際級的軟體大會！

相關連結

• 官方回顧文章

你敢信？我這個個人網站的架設除了域名之外都是免費的！畢竟這只是我打算拿來發廢文的網站，能當免費仔就當免費仔。下面來講我怎麼搭建這個網站的。

框架選擇

既然要免費，那就不能選擇像是 WordPress 那種 SSR（Server-Side Rendering）的框架，畢竟要部屬到主機上面就要錢了，雖然有些雲端平台有提供免費額度，但隨著瀏覽人數變多勢必要花錢。因此選擇 SSG（Static Side Generation）的框架然後部屬在有提供免費 Static Site Hosting 的平台更為合理。

我之前的網站是使用 Gatsby 這個框架，原因也很簡單，因為我非常熟悉 React ，想說之後要客製化比較簡單，但後來發現我實在沒時間維護一堆 Typescript 和 Javascript，導致後來我都很懶得更新我的個人網站。因此這次我選擇使用 Hugo ，維護少量的 Go Template 至少比較輕鬆，而且我剛好也會 Golang。

版型選擇

Hugo 的官網提供了許多版型可以選擇 ，我這次選擇的是 hugo-PaperMod 這個版型。版型通常會提供下載步驟，照著做就行了。

1
2
3
4

hugo new site personal-website --format yaml
cd personal-website
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive

設定

這個就只能照著不同的版型提供的文件去慢慢設定成自己想要的樣子了，下面只講一些比較難設定的東西。

多語言

我選用的這個版型有支援多語言，但是地方沒有翻譯好，這個就沒辦法了，只能去看原始碼自己找辦法解決，或是可以去搜尋 issues 看看有沒有人提出解法，例如我就找到了一些解法：

• https://github.com/adityatelange/hugo-PaperMod/issues/46

最後修改時間

同樣是去 issues 裡面搜尋解法

• https://github.com/adityatelange/hugo-PaperMod/issues/1037

中文字體

通常版型都不會特別對中文字體做設定，所以中文字會很醜。我比較常用 Web font 的方式解決，比較方便，這裡使用 Google 的 Noto Sans Traditional Chinese 這個字體。

首先必須先去複製字體的 embed code，點選 Get fonts

之後點 Get embed code

然後點 copy code

接著需要去版型的原始碼裡面找一下要插入 HTML tags 到 head 底下要插入在哪裡，經過搜尋之後發現是 這個檔案 ，於是我們必須創一個檔案叫做 layouts/partials/extend_head.html 然後把剛才複製的內容寫進去。

再來需要去版型的原始碼裡面找一下控制字體的 css 在哪，經過搜尋之後 我發現是這一行

創一個檔案叫做 assets/css/extended/custom-font.css 然後寫入以下內容：

1
2
3
4

body:lang(zh-tw) {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen,
    Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", "Noto Sans TC", sans-serif;
}

注意這一段就是直接從原本的程式碼抄過來，加上 body:lang(zh-tw) 的 selector 去覆蓋掉繁體中文的字體風格，但因為我的文章是中英文混雜的，為了不改變到英文字體，所以 "Noto Sans TC" 要放在 fallback font 的前面，也就是 sans-serif 的前面。

留言板

因為我們的網站是 Static Site，因此必須依靠外部服務來提供留言板功能，最有名的應該是 Disqus 。但這個服務的免費方案會有一堆廣告顯示在網站上，我覺得不是很好，因此最後選擇使用 giscus ，這是使用 GitHub Discussions 當作留言的存放地方，唯一缺點是不像 Disqus 可以讓使用者用 Google 或社群媒體帳號登入留言，但我的文章目前應該都會是技術文章，看技術文章的人應該都有 GitHub，所以問題不大。

比較麻煩的是我必須讓這個留言板支援多語言和 light、dark mode 切換，所以必須自己寫一點 Javascript，最後大概長這樣（一些敏感資訊已被替換掉）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

<div id="giscus-script" />

<script>
  let lang = document.documentElement.lang;
  let category = "English Comments";
  let categoryId = "<your-category-id>";
  if (lang === "zh-tw") {
    lang = "zh-TW";
    category = "Traditional Chinese Comments";
    categoryId = "<your-category-id>";
  }

  let theme = localStorage.getItem("pref-theme");
  if (theme !== "light" && theme !== "dark") {
    theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? "dark" : "light";
  }

  const giscusAttributes = {
    "src": "https://giscus.app/client.js",
    "data-repo": "<your-repo>",
    "data-repo-id": "<your-repo-id>",
    "data-category": category,
    "data-category-id": categoryId,
    "data-mapping": "pathname",
    "data-strict": "1",
    "data-reactions-enabled": "1",
    "data-emit-metadata": "0",
    "data-input-position": "top",
    "data-theme": theme,
    "data-lang": lang,
    "data-loading": "lazy",
    "crossorigin": "anonymous",
    "async": "",
  };
  const giscusScript = document.createElement("script");
  Object.entries(giscusAttributes).forEach(([key, value]) =>
    giscusScript.setAttribute(key, value)
  );
  document.getElementById("giscus-script").appendChild(giscusScript);

  function setGiscusTheme(theme) {
    if (giscusScript) {
      giscusScript.remove();
      const newGiscusScript = document.createElement("script");
      Object.entries(giscusAttributes).forEach(([key, value]) =>
        newGiscusScript.setAttribute(key, value)
      );
      newGiscusScript.setAttribute('data-theme', theme); // Set the new theme
      document.getElementById("giscus-script").appendChild(newGiscusScript);
    }
  }

  function handleStorageChange() {
    const theme = localStorage.getItem('pref-theme');
    setGiscusTheme(theme);
  }

  window.addEventListener("storage", (event) => {
    if (event.key === 'pref-theme') {
      handleStorageChange();
    }
  });

  // Override the localStorage setItem method to detect changes in the same browsing context
  const originalSetItem = localStorage.setItem;
  localStorage.setItem = function(key, value) {
    originalSetItem.apply(this, arguments);
    if (key === 'pref-theme') {
      handleStorageChange();
    }
  };
</script>

部屬

Static Site Hosting 的平台很多，包含 GitHub Pages 、 Netlify 、 Cloudflare Pages 等，我選用 Cloudflare Pages，原因很簡單，因為他的免費方案的限制最少，甚至沒有頻寬限制。

部屬非常簡單，照著 官方的文件 ，連接 GitHub repo 之後，build command 選擇 hugo 就行了。

CMS

每次都要坐到電腦前面，打開文字編輯器，才有辦法寫部落格，不是很方便，常見解法是用 CMS（Content Management System），以前我都是用 Decap CMS （之前叫做 Netlify CMS），但他對接 GitHub repo 不是很方便，而且 YAML frontmatter 和 body 之間不會產生空行，有時候會有點問題。所以這次我用 Tina CMS 。剛好 Tina Cloud 2 人以下是免費的。

設定 Tina CMS 其實沒有很難，照著官網設定完之後，去 Cloudflare Pages 把 build command 改成 git fetch --unshallow && npx --yes tinacms build && [ "$CF_PAGES_BRANCH" = "main" ] && hugo --minify || hugo -b $CF_PAGES_URL --minify 並且把 Environment variables 都加上去就行了。效果會像這樣：

SEO

Favicon

Favicon 是網頁上面的小圖案，沒有設定的話在 Chrome 裡面就會變成一顆地球，不是很好。

去 Favicon Generator ，丟一個圖片上去，然後把檔案下載下來，解壓縮之後把裡面的檔案全部複製到 static 資料夾裡面。之後參考各個版型的文件要怎麼設定 favicon。

OpenGraph

OpenGraph 是你的網站被分享到社群網站的時候的的一些圖片、描述等設定。可以使用 https://www.opengraph.xyz/ 這個網站來檢查你的網站被分享到社群網站的樣子會長怎樣。

Google Search Console

把網站提交到 Google Search Console 可以加快被 Indexing 的速度。在裡面可以提交 sitemap，記得把 sitemap 也提交上去，XML 和 RSS 的 sitemap 都提交，可以再加快 indexing 的速度。

LightHouse

LightHouse 可以用來測量網站的效能、SEO 等。首先先用無痕視窗開啟網站，避免被 Chrome 插件影響。接著按 Ctrl+Shift+J 進入 Chrome Dev Tools，然後選擇 LightHouse 分頁

選擇 Desktop 然後點擊 Analyze page load

結果：

備註：Google Web Font 效能調校

當使用 Lighthouse 時可能會發現有一個效能問題是來自於 Google Web Font，此時可以使用 preload 的方式解決：

1	<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+TC:wght@100..900&display=swap" rel="preload" as="font" crossorigin="anonymous">

統計資料

要統計網頁資料，例如瀏覽人數等，最常用的是 Google Analytics ，超出本篇範圍，故不詳述。

結語

部屬一個網站其實要注意的細節不少，很多主題這篇文章也只是粗略帶過，畢竟不同的框架和版型要做的設定都會有點不太一樣。雖然看完這篇文章沒辦法直接復刻出一個網頁，但希望看完這篇文章可以讓你在部署自己的個人網站的時候去注意到這些細節。

前幾天在開發 KubeRay 專案的時候，從 issue 的留言區 學到了一個 Kubernetes 的知識，原來 Eviction 還有分 Node-pressure Eviction 和 API-initiated Eviction 兩種。API-initiated Eviction 是直接 call API，或是使用像是 kubectl drain 之類的指令，特性是不管怎樣最終以這種方式被 Evict 的 Pod 會被 delete 掉，通常就會在另一個 node 上被重新 create。但是如果是 Node-pressure Eviction 的話，kubelet 只會把 Pod 的 Phase 設成 Failed，而不會把 Pod delete 掉，所以 controller 沒有特別處理的話，Pod 就不會在另一個 node 上面被重新 create。

現在簡述一下這個 issue 的問題：當 KubeRay operator 創出來的某個 Pod 的所在的 node 如果遇到 disk 容量不夠，該 Pod 會被 Evict，稍後 disk 容量被清出來之後，該 Pod 仍然處於 Failed 狀態，也沒有被重新 create 在其他 node 上。

現在我需要 reproduce 這個 issue，但重點來了，既然這兩種 Eviction 的行為不同，這表示我不能直接用 kubectl drain 之類的指令去 reproduce 出這個 issue 的情境，必須確確實實的弄出 Node-pressure Eviction。但是我也沒有 cluster 可以使用，我都是用個人電腦開發的，這導致我很難 reproduce 出這個 issue。原因是如果是在本機開發 Kubernetes 相關的應用程式，大部分會使用 minikube 、 kind 或是 k3d 。我要模擬的情境必須要有多個 node，因此先排出 minikube，雖然 它現在也支援 multiple nodes 了，但是它還是比較常用來開發 single node 的情境。而 kind 和 k3d 上使用 Docker container 去當作 Kubernetes nodes，而我的作業系統是 Linux Mint，Docker 是原生的 Docker，不像 macOS 的 Docker 是跑在虛擬機裡的，如果我要搞出 Node-pressure 的情境，因為資源（memory、disk 等）都是跟本機共用的，所以我如果真的把某個 node 搞到有 pressure 我的電腦大概也不能用了。

經過瘋狂 Google 過後，我發現 Docker 可以設定 Runtime 的 Memory 限制 ，還有 k3d 有個 –agents-memory 的 flag 可以設定 agent node 的 memory ，我才找到 重現這個 issue 的辦法 。

步驟

首先創一個 k3d cluster，有 2 個 agent nodes，每個 agent node 有 3GB 的 memory，並且在剩餘可用 memory 少於 1GiB 的時候就會開始觸發 Pod Eviction。

1
2
3
4
5
6

k3d cluster create \
  --agents 2 \
  --k3s - arg "--disable=traefik@server:0" \
  --agents - memory 3g \
  --k3s - arg "--kubelet-arg=eviction-hard=memory.available<1Gi@agent:0" \
  --k3s - arg "--kubelet-arg=eviction-hard=memory.available<1Gi@agent:1"

檢查所有 Node 的記憶體

1

kubectl get nodes -o custom-columns=NAME:.metadata.name,CAPACITY_MEMORY:.status.capacity.memory,ALLOCATABLE_MEMORY:.status.allocatable.memory

輸出：

# NAME                       CAPACITY_MEMORY   ALLOCATABLE_MEMORY
# k3d-k3s-default-agent-1    3221225Ki         2172649Ki
# k3d-k3s-default-agent-0    3221225Ki         2172649Ki
# k3d-k3s-default-server-0   32590664Ki        32590664Ki

可以看到 agent 0 和 agent 1 都有 3GB 的記憶體，但可以 allocate 的記憶體是 2GB，因為剩餘記憶體不足 1GiB 的時候就會觸發 Pod Eviction。

接著把 agent 0 和 agent 1 上面加上 taint，這樣之後的 Pod 都只會被 deploy 到 server-0 這個 node 上面。

1
2

kubectl taint nodes k3d-k3s-default-agent-0 k3d=noschedule:NoSchedule
kubectl taint nodes k3d-k3s-default-agent-1 k3d=noschedule:NoSchedule

安裝 KubeRay operator，這時 operator Pod 會跑在 server-0 這個 node 上。

1

helm install kuberay-operator kuberay/kuberay-operator --namespace ray-system --version 1.1.1 --create-namespace

移除 agent 0 和 agent 1 的 taint，為 server 0 加上 taint，這樣之後的 Pod 就不會被 deploy 到 server 0 上面。

1
2
3

kubectl taint nodes k3d-k3s-default-server-0 k3d=noschedule:NoSchedule
kubectl taint nodes k3d-k3s-default-agent-0 k3d=noschedule:NoSchedule-
kubectl taint nodes k3d-k3s-default-agent-1 k3d=noschedule:NoSchedule-

安裝 RayCluster custom resource，安裝完後 KubeRay operator 會創出一個 head pod 和一個 worker pod，因為在 helm chart 裡面 head pod 的 memory resource request 是 2G，worker pod 是 1G，而 agent 0 和 agent 1 都只有 2G 的可分配記憶體，所以這兩個 Pod 一定不會在同一個 node 上面。

1

helm install raycluster kuberay/ray-cluster --version 1.1.1

接下來要進入 head pod 所在的 node 裡面執行記憶體壓力測試，一樣 Google 完發現大家常用的是 stress-ng ，所以就用它。我們必須讓 head pod 裡面有 stress-ng 可以用，最簡單的方式是把靜態編譯過的 stress-ng 直接複製到 head pod 裡面，這樣就不用管 head pod 的 base image 是什麼、缺了什麼 dependency 之類的。至於要怎麼取得靜態編譯過的執行檔，可以自己編譯，但我比較懶，我直接去把 一個裡面帶有靜態編譯執行檔的 docker image 裡面的執行檔複製出來 。假設 head pod 的名字是 raycluster-kuberay-head-ldg9f

1

kubectl cp ./stress-ng raycluster-kuberay-head-ldg9f:/home/ray

開一個在 head pod 上面的 shell

1

kubectl exec -it raycluster-kuberay-head-ldg9f -- bash

模擬記憶體不足情形

1

./stress-ng --vm 4 --vm-bytes 2G --vm-keep

如此一來就可以看到 head pod 被 Evict 掉，而且是 Node-pressure Eviction。